keystone-agent-sdk 0.3.0__py3-none-any.whl

keystone/agent_sdk/__init__.py

@@ -0,0 +1,47 @@
+"""Keystone AI — pro-code agent SDK (``keystone.agent_sdk``).
+
+The developer's interface to the platform for **authoring** agents (FR-04 / FDP-3072).
+M1 (walking skeleton) surface:
+
+* **Authoring** — build the graph with **LangGraph directly** (``from langgraph.graph import
+  StateGraph``) + tools with ``langchain_core`` (``from langchain_core.tools import tool``). The
+  SDK does NOT wrap them, so an existing LangGraph agent runs here **unchanged**.
+* **Manifest** — :class:`AgentManifest` (the ``agent.yaml`` schema, owned by the SDK
+  and shared by validate / run / deploy) + :func:`load_manifest`.
+* **Validation** — :func:`validate` (manifest + entrypoint importability).
+* **HITL** — :func:`request_approval` (stub; lands in M3 — FDP-3078).
+
+Building-block clients live in the ``keystone.agent_sdk.clients`` subpackage
+(``from keystone.agent_sdk.clients import GatewayClient, RAGClient`` — FDP-3118) — kept OFF the
+top-level import so authoring-only agents don't pull the HTTP / request-context deps. The CLI
+(``keystone agent run/validate``) is the separate ``keystone-cli`` package (FDP-3120).
+
+Usage::
+
+    from langgraph.graph import StateGraph          # graph = LangGraph, the SDK doesn't wrap it
+    from keystone.agent_sdk import AgentManifest, validate
+    from keystone.agent_sdk.clients import GatewayClient, RAGClient
+"""
+
+from .durable import durable_task, idempotency_key
+from .hitl import request_approval
+from .loader import GraphLoadError, load_graph
+from .manifest import AgentManifest, Dependencies, HitlSpec, Identity, ResourceSpec, SecretRef, load_manifest
+from .validate import ValidationResult, validate
+
+__all__ = [
+    "AgentManifest",
+    "Dependencies",
+    "GraphLoadError",
+    "HitlSpec",
+    "Identity",
+    "ResourceSpec",
+    "SecretRef",
+    "ValidationResult",
+    "durable_task",
+    "idempotency_key",
+    "load_graph",
+    "load_manifest",
+    "request_approval",
+    "validate",
+]

keystone/agent_sdk/bundle.py

@@ -0,0 +1,183 @@
+"""Package an agent project into a deterministic ``bundle.tar.gz`` + SHA-256 (deploy, FDP-3169).
+
+Backs ``keystone agent deploy``: tar the project (source + agent.yaml + uv.lock) honouring ``.gitignore``,
+skipping VCS/venv/cache junk. The SHA-256 (over the UNCOMPRESSED, normalized tar) is a stable idempotency
+key — the same source produces the same hash, so a re-deploy dedupes to the existing version (cf. RAG file
+upload). stdlib-only (no new dep); NOT re-exported at package top-level (deploy-time, not authoring).
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import gzip
+import hashlib
+import io
+import re
+import tarfile
+from dataclasses import dataclass
+from dataclasses import field as dataclass_field
+from pathlib import Path
+
+# Always excluded regardless of .gitignore — VCS, venvs, caches, editor/OS cruft, build output.
+_ALWAYS_IGNORE_DIRS = frozenset(
+    {
+        ".git",
+        ".venv",
+        "venv",
+        "env",
+        "__pycache__",
+        ".mypy_cache",
+        ".ruff_cache",
+        ".pytest_cache",
+        "node_modules",
+        ".idea",
+        ".vscode",
+        "dist",
+        "build",
+        ".keystone",
+    }
+)
+# `.env*` is excluded UNCONDITIONALLY, not left to .gitignore. It is the file the dev is told to put
+# their platform API key in (`RT_AGENT_API_KEY`, access-policy.md §4.2), and a bundle is not a private
+# thing: it lands in S3 and is baked into the agent's image in ECR — where retire/delete cleanup is
+# still OFF (technical-debt.md §7), so a copy outlives a revoked key. Nothing needs it there either:
+# a pod gets its env from the operator (ConfigMap/Secret), and `.env` only exists because
+# `RuntimeSettings` reads `env_file=".env"` for LOCAL runs. Relying on the project's .gitignore would
+# make this depend on a file the dev edits — and the scaffold's .gitignore didn't list `.env` at all
+# until this change, so every project generated before it would have shipped the key.
+_ALWAYS_IGNORE_GLOBS = ("*.pyc", "*.pyo", "*.egg-info", ".DS_Store", "*.log", ".env", ".env.*")
+
+# The platform API key format (`ak_<env>_<short_id>.<secret>`, agent-identity reference / platform
+# `api_keys`). Distinctive enough to match on directly, which is the point: this is a targeted check
+# for OUR credential, not a general-purpose secret scanner (detect-secrets already runs pre-commit).
+# Catches the key wherever it was pasted — `agent.yaml`'s `config:`, source, a README, or a `.env`
+# variant under a name the glob above doesn't cover.
+_API_KEY_RE = re.compile(r"\bak_[a-z0-9]{2,16}_[A-Za-z0-9]{4,}\.[A-Za-z0-9_-]{16,}")
+
+# Cap per-file scanning: a bundle may legitimately carry a model or fixture, and reading a 500 MB
+# file to look for a 60-char token is not worth it. Anything that fails to decode as UTF-8 is binary
+# and skipped for the same reason.
+_SCAN_MAX_BYTES = 1 << 20  # 1 MiB
+
+
+class SecretInBundleError(Exception):
+    """A bundled file contains a platform API key. Carries ``file``/``line`` — never the value.
+
+    The value is deliberately NOT in the message: this surfaces in terminal scrollback and CI job
+    logs, so echoing the credential there would leak it a second time in the act of reporting it.
+    """
+
+    def __init__(self, file: str, line: int) -> None:
+        super().__init__(
+            f"{file}:{line} contains what looks like a platform API key (ak_<env>_<id>.<secret>). "
+            "Refusing to package it: a bundle is uploaded to S3 and baked into the agent image in "
+            "ECR, so the key would outlive being revoked. Put it in .env (never bundled) and let the "
+            "operator inject it, or reference it from the portal — do not commit it."
+        )
+        self.file = file
+        self.line = line
+
+
+@dataclass
+class BundleResult:
+    """A packaged agent project. ``data`` = gzip bytes to upload; ``sha256`` = idempotency key.
+
+    ``skipped_env`` names the env files left out (see ``_ALWAYS_IGNORE_GLOBS``). Reported so the
+    caller can SAY it: a dev who put config in ``.env`` and sees it missing at runtime would
+    otherwise have no way to know the packager dropped it on purpose.
+    """
+
+    data: bytes
+    sha256: str
+    file_count: int
+    skipped_env: list[str] = dataclass_field(default_factory=list)
+
+
+def _gitignore_patterns(root: Path) -> list[str]:
+    gi = root / ".gitignore"
+    if not gi.is_file():
+        return []
+    out: list[str] = []
+    for raw in gi.read_text(encoding="utf-8", errors="replace").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or line.startswith("!"):  # negation unsupported (v1)
+            continue
+        out.append(line.rstrip("/"))
+    return out
+
+
+def _is_ignored(rel: Path, patterns: list[str]) -> bool:
+    if set(rel.parts) & _ALWAYS_IGNORE_DIRS:
+        return True
+    name, rel_str = rel.name, str(rel)
+    if any(fnmatch.fnmatch(name, g) for g in _ALWAYS_IGNORE_GLOBS):
+        return True
+    return any(
+        fnmatch.fnmatch(name, p) or fnmatch.fnmatch(rel_str, p) or any(fnmatch.fnmatch(seg, p) for seg in rel.parts)
+        for p in patterns
+    )
+
+
+def create_bundle(project_dir: str | Path) -> BundleResult:
+    """Tar+gzip ``project_dir`` (deterministic: sorted, mtime/uid/gid/mode normalized) → BundleResult.
+
+    Raises ``NotADirectoryError`` if the path isn't a directory, ``FileNotFoundError`` if there's no
+    ``agent.yaml`` (a deploy without a manifest is a mistake), and :class:`SecretInBundleError` if a
+    file that WOULD be packaged carries a platform API key."""
+    root = Path(project_dir).resolve()
+    if not root.is_dir():
+        raise NotADirectoryError(f"not a directory: {root}")
+    if not (root / "agent.yaml").is_file():
+        raise FileNotFoundError(f"no agent.yaml in {root} — not an agent project")
+
+    patterns = _gitignore_patterns(root)
+    tar_buf = io.BytesIO()
+    count = 0
+    skipped_env: list[str] = []
+    # Uncompressed tar, sorted + normalized → the hash is stable across machines/times.
+    with tarfile.open(fileobj=tar_buf, mode="w") as tar:
+        for path in sorted(p for p in root.rglob("*") if p.is_file()):
+            rel = path.relative_to(root)
+            if _is_ignored(rel, patterns):
+                if _is_env_file(rel):
+                    skipped_env.append(str(rel))
+                continue
+            payload = path.read_bytes()
+            # Check BEFORE adding: the exception must leave no half-built tar behind, and a bundle
+            # that was already assembled is a bundle someone can accidentally upload.
+            _reject_api_key(str(rel), payload)
+            info = tarfile.TarInfo(name=str(rel))
+            info.size = len(payload)
+            info.mtime = 0
+            info.mode = 0o644
+            info.uid = info.gid = 0
+            info.uname = info.gname = ""
+            tar.addfile(info, io.BytesIO(payload))
+            count += 1
+
+    tar_bytes = tar_buf.getvalue()
+    sha256 = hashlib.sha256(tar_bytes).hexdigest()
+    data = gzip.compress(tar_bytes, mtime=0)  # mtime=0 → deterministic gzip too
+    return BundleResult(data=data, sha256=sha256, file_count=count, skipped_env=skipped_env)
+
+
+def _is_env_file(rel: Path) -> bool:
+    """True for the env-file shapes ``_ALWAYS_IGNORE_GLOBS`` drops (``.env``, ``.env.local``, …)."""
+    return rel.name == ".env" or rel.name.startswith(".env.")
+
+
+def _reject_api_key(rel: str, payload: bytes) -> None:
+    """Raise :class:`SecretInBundleError` if ``payload`` carries a platform API key.
+
+    Binary and oversized files are skipped rather than scanned — see ``_SCAN_MAX_BYTES``. A key can
+    only be *pasted* as text, so decoding failure is a reliable "not it" rather than a blind spot.
+    """
+    if len(payload) > _SCAN_MAX_BYTES:
+        return
+    try:
+        text = payload.decode("utf-8")
+    except UnicodeDecodeError:
+        return
+    for lineno, line in enumerate(text.splitlines(), start=1):
+        if _API_KEY_RE.search(line):
+            raise SecretInBundleError(rel, lineno)

keystone/agent_sdk/clients/__init__.py

@@ -0,0 +1,27 @@
+"""Building-block clients for pro-code agents (FDP-3118).
+
+M1 ships ``GatewayClient`` (chat/embeddings) + ``RAGClient`` (search) — the ``rag-qa`` agent's
+deps. guardrails / memory / skill clients land as their stories ship. All clients auto-attach
+the caller identity (from the request-context ContextVar the runtime sets per run) and decode
+errors to :class:`GatewayError`.
+"""
+
+from keystone.agent_sdk.clients._base import BaseClient
+from keystone.agent_sdk.clients._errors import (
+    GatewayError,
+    GatewayForbiddenError,
+    GatewayRateLimitedError,
+    GatewayUpstreamError,
+)
+from keystone.agent_sdk.clients.gateway import GatewayClient
+from keystone.agent_sdk.clients.rag import RAGClient
+
+__all__ = [
+    "BaseClient",
+    "GatewayClient",
+    "GatewayError",
+    "GatewayForbiddenError",
+    "GatewayRateLimitedError",
+    "GatewayUpstreamError",
+    "RAGClient",
+]

keystone/agent_sdk/clients/_base.py

@@ -0,0 +1,56 @@
+"""Shared base for the SDK building-block clients (proposal §3.5a: ContextVar identity +
+typed error decode + singleton httpx).
+
+The client attaches caller-identity headers from the request-context ContextVar that the agent
+runtime sets per run (``keystone.request_context.gateway_identity_headers``) — the agent author
+never sets headers. One ``httpx.AsyncClient`` per client instance (connection pooling).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+from keystone.agent_sdk.clients._errors import decode_gateway_error
+from keystone.agent_sdk.tracing import inject_traceparent
+from keystone.request_context import gateway_identity_headers
+
+
+class BaseClient:
+    """Base HTTP client — identity injection + error decode. Subclasses add typed methods."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        auth_token: str = "",
+        caller_service: str = "agent",  # gateway X-Caller-Service vocab for an agent-runtime caller (Arch §10)
+        timeout_s: float = 60.0,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._auth_token = auth_token
+        self._caller_service = caller_service
+        self._http = httpx.AsyncClient(
+            limits=httpx.Limits(max_keepalive_connections=20, max_connections=40),
+            timeout=httpx.Timeout(timeout_s),
+        )
+
+    def _headers(self, operation: str) -> dict[str, str]:
+        headers = gateway_identity_headers(
+            auth_token=self._auth_token,
+            operation=operation,
+            caller_service=self._caller_service,
+        )
+        # FDP-3436: propagate the run's trace context so downstream hops (rag,
+        # llm-gateway) can join the trace. No active span (offline run) → no-op.
+        return inject_traceparent(headers)
+
+    async def _post(self, path: str, body: dict[str, Any], *, operation: str) -> dict[str, Any]:
+        response = await self._http.post(f"{self._base_url}{path}", json=body, headers=self._headers(operation))
+        if response.status_code >= 400:
+            raise decode_gateway_error(response)
+        return response.json()
+
+    async def aclose(self) -> None:
+        """Close the connection pool. Idempotent."""
+        await self._http.aclose()

keystone/agent_sdk/clients/_errors.py

@@ -0,0 +1,92 @@
+"""Typed errors for the SDK building-block clients.
+
+SDK-LOCAL copy of the gateway error-decode shape (FDP-3118 scope call — `decode_gateway_error`
+is NOT lifted to a shared lib this milestone; promote to ``keystone.errors`` when the
+guardrails/memory/skill clients land). The envelope is the keystone-standard
+``{"error": {"code", "message", "request_id"}}`` — so the same decoder serves rag responses too
+(a rag error decodes to :class:`GatewayError` carrying its ``RAG_*`` code).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import httpx
+
+
+class GatewayError(Exception):
+    """A building-block call returned a non-2xx envelope."""
+
+    def __init__(
+        self,
+        *,
+        code: str,
+        message: str,
+        request_id: str | None = None,
+        retry_after: int | None = None,
+    ) -> None:
+        super().__init__(f"[{code}] {message}")
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+        self.retry_after = retry_after
+
+
+class GatewayForbiddenError(GatewayError):
+    """Caller not permitted (model not allowed / unauthorized / invalid key)."""
+
+
+class GatewayRateLimitedError(GatewayError):
+    """Provider throttle / budget — carries ``retry_after`` when the server sent one."""
+
+
+class GatewayUpstreamError(GatewayError):
+    """Upstream/provider 5xx or gateway self-error — retryable after backoff."""
+
+
+_ERROR_CODE_MAP: dict[str, type[GatewayError]] = {
+    "LLM_MODEL_NOT_ALLOWED": GatewayForbiddenError,
+    "LLM_MODEL_UNAVAILABLE": GatewayForbiddenError,
+    "LLM_UNAUTHORIZED": GatewayForbiddenError,
+    "LLM_INVALID_KEY": GatewayForbiddenError,
+    "LLM_INVALID_CALLER_IDENTITY": GatewayForbiddenError,
+    "LLM_PROVIDER_RATE_LIMITED": GatewayRateLimitedError,
+    "LLM_BUDGET_EXCEEDED": GatewayRateLimitedError,
+    "LLM_COST_CEILING_EXCEEDED": GatewayRateLimitedError,
+    "LLM_PROVIDER_ERROR": GatewayUpstreamError,
+    "LLM_UPSTREAM_ERROR": GatewayUpstreamError,
+    "LLM_UPSTREAM_TIMEOUT": GatewayUpstreamError,
+    "LLM_PROVIDER_UNAVAILABLE": GatewayUpstreamError,
+    "LLM_NO_PROVIDERS_AVAILABLE": GatewayUpstreamError,
+    "LLM_INTERNAL_ERROR": GatewayUpstreamError,
+}
+
+
+def _parse_retry_after(response: httpx.Response) -> int | None:
+    raw = response.headers.get("Retry-After")
+    if not isinstance(raw, str):
+        return None
+    try:
+        secs = int(raw.strip())
+    except ValueError:
+        return None
+    return secs if secs > 0 else None
+
+
+def decode_gateway_error(response: httpx.Response) -> GatewayError:
+    """Decode a non-2xx response into a typed :class:`GatewayError`.
+
+    Defensive: a non-JSON / non-envelope body (infra error page) falls back to ``HTTP_<status>``.
+    """
+    try:
+        envelope = (response.json().get("error")) or {}
+        code = envelope.get("code") or f"HTTP_{response.status_code}"
+        message = envelope.get("message") or response.text[:500]
+        request_id = envelope.get("request_id")
+    except (ValueError, AttributeError):
+        code = f"HTTP_{response.status_code}"
+        message = response.text[:500] or response.reason_phrase
+        request_id = None
+    exc_cls = _ERROR_CODE_MAP.get(code, GatewayError)
+    return exc_cls(code=code, message=message, request_id=request_id, retry_after=_parse_retry_after(response))

keystone/agent_sdk/clients/gateway.py

@@ -0,0 +1,56 @@
+"""``GatewayClient`` — chat completions + embeddings via llm-gateway (OpenAI-compatible).
+
+Endpoints from ``specs/api/llm-gateway.openapi.yaml``. Identity headers + error decode are
+handled by :class:`~keystone.agent_sdk.clients._base.BaseClient`.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from keystone.agent_sdk.clients._base import BaseClient
+from keystone.agent_sdk.tracing import genai_span, link_generation, record_usage
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+_CHAT_PATH = "/api/llm-gateway/v1/chat/completions"
+_EMBEDDINGS_PATH = "/api/llm-gateway/v1/embeddings"
+
+
+class GatewayClient(BaseClient):
+    async def chat(
+        self,
+        *,
+        messages: list[dict[str, str]],
+        model: str,
+        max_tokens: int = 1024,
+        temperature: float = 0.0,
+        **extra: Any,
+    ) -> dict[str, Any]:
+        """OpenAI-compatible chat completion. Returns the raw gateway JSON."""
+        body: dict[str, Any] = {
+            "model": model,
+            "messages": messages,
+            "max_tokens": max_tokens,
+            "temperature": temperature,
+            **extra,
+        }
+        # FDP-3436: SDK-owned GenAI span (spike Q3) — token usage from the response;
+        # no-op when the host process has no tracer (local `agent run`).
+        with genai_span("chat", model) as span:
+            # FDP-3663: must be INSIDE the span — it stamps that span's id into the body so
+            # LiteLLM's generation nests under it instead of dangling at the trace root.
+            link_generation(span, body)
+            result = await self._post(_CHAT_PATH, body, operation="chat_completion")
+            record_usage(span, result)
+        return result
+
+    async def embeddings(self, *, texts: Sequence[str], model: str, **extra: Any) -> dict[str, Any]:
+        """Vector embeddings for ``texts``. Returns the raw gateway JSON."""
+        body: dict[str, Any] = {"model": model, "input": list(texts), **extra}
+        with genai_span("embeddings", model) as span:
+            link_generation(span, body)
+            result = await self._post(_EMBEDDINGS_PATH, body, operation="embedding")
+            record_usage(span, result)
+        return result

keystone/agent_sdk/clients/rag.py

@@ -0,0 +1,32 @@
+"""``RAGClient`` — hybrid search via the rag service.
+
+Path verified against the ``services/rag`` search router (prefix ``/knowledge-bases``). ``search``
+targets the multi-KB endpoint (``/api/rag/v1/knowledge-bases/search`` with ``kb_ids`` in the body).
+Response = ``{"results": [{"content", "chunk_id", "score", ...}], ...}`` (no ``data`` envelope).
+Identity headers + error decode via :class:`~keystone.agent_sdk.clients._base.BaseClient`.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from keystone.agent_sdk.clients._base import BaseClient
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+_SEARCH_PATH = "/api/rag/v1/knowledge-bases/search"
+
+
+class RAGClient(BaseClient):
+    async def search(
+        self,
+        *,
+        query: str,
+        kb_ids: Sequence[str],
+        top_k: int = 5,
+        **extra: Any,
+    ) -> dict[str, Any]:
+        """Hybrid retrieval across ``kb_ids``. Returns the raw rag JSON (chunks + citations)."""
+        body: dict[str, Any] = {"query": query, "kb_ids": list(kb_ids), "top_k": top_k, **extra}
+        return await self._post(_SEARCH_PATH, body, operation="search")

keystone/agent_sdk/durable.py

@@ -0,0 +1,156 @@
+"""Durable-task discipline for paid / side-effecting steps (M3.3 — FDP-3334).
+
+Spike-verified premise (langgraph 1.1.10 + AsyncPostgresSaver, see
+``services/agent-runtime/tests/integration/test_task_memoization.py``): when a node
+crashes AFTER a ``langgraph.func.task`` call completed, the task's result is already
+persisted with the checkpoint; on resume (``ainvoke(None)`` — the platform worker's
+convention) the node body re-runs but completed tasks **replay from the checkpoint
+instead of re-executing**. Wrap every expensive step (LLM call, paid API, mutation)
+in :func:`durable_task` and a crash-resumed run re-bills only the in-flight step.
+
+Two rules make the replay trustworthy, and this module owns both:
+
+* **Memo-safe arguments** — replay matches tasks by their deterministic position in
+  the node's call sequence, so arguments must be *values*, not live handles or
+  freshly-minted timestamps. :func:`durable_task` validates every call's arguments
+  and rejects clients / connections / callables (construct them INSIDE the task
+  body) and ``datetime`` objects (pass pre-computed ISO strings, or move ``now()``
+  inside the task body so it is captured with the memoized result).
+* **Idempotency keys for mutations** — memoization stops the *node-retry* double
+  fire, but the crash can still land INSIDE a mutating call (money moved, ticket
+  created — then SIGKILL before the result persisted). Downstream dedup is the only
+  fix: send :func:`idempotency_key` with every mutating call so the retried call is
+  recognised. This gate is review-enforced (``.claude/references/review-checklist.md``),
+  not runtime-enforced.
+
+Usage::
+
+    from keystone.agent_sdk import durable_task, idempotency_key
+
+    @durable_task
+    async def draft_reply(ticket: str) -> str:          # paid LLM call
+        return await llm.ainvoke(ticket)                # client built/closed inside
+
+    async def triage(state: State, config: RunnableConfig) -> dict:
+        draft = await draft_reply(state["ticket"])      # replayed, not re-billed, on resume
+        key = idempotency_key(
+            config["configurable"]["thread_id"], "triage", f"create-ticket:{state['id']}"
+        )
+        await helpdesk.create(draft, idempotency_key=key)
+        return {"draft": draft}
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, overload
+
+from langgraph.func import task
+from pydantic import BaseModel
+
+if TYPE_CHECKING:
+    from langgraph.types import RetryPolicy
+
+_SCALARS = (type(None), bool, int, float, str, bytes)
+
+
+def _assert_memo_safe(value: Any, path: str) -> None:
+    """Reject arguments that would make a durable task's replay non-deterministic."""
+    if isinstance(value, _SCALARS):
+        return
+    if isinstance(value, (list, tuple)):
+        for i, item in enumerate(value):
+            _assert_memo_safe(item, f"{path}[{i}]")
+        return
+    if isinstance(value, dict):
+        for k, item in value.items():
+            if not isinstance(k, str):
+                raise TypeError(
+                    f"durable_task argument {path} has a non-string dict key {k!r}; "
+                    "memo-safe arguments use string keys only"
+                )
+            _assert_memo_safe(item, f"{path}[{k!r}]")
+        return
+    if isinstance(value, BaseModel):
+        _assert_memo_safe(value.model_dump(), path)
+        return
+    # datetime/date/time before the generic reject, for a targeted message.
+    import datetime as _dt
+
+    if isinstance(value, (_dt.datetime, _dt.date, _dt.time)):
+        raise TypeError(
+            f"durable_task argument {path} is a {type(value).__name__} — timestamps make "
+            "the replayed call non-deterministic. Pass a pre-computed ISO string, or move "
+            "now() inside the task body so it is captured with the memoized result."
+        )
+    if isinstance(value, (set, frozenset)):
+        raise TypeError(
+            f"durable_task argument {path} is a {type(value).__name__} — iteration order "
+            "is non-deterministic; pass a sorted list instead"
+        )
+    raise TypeError(
+        f"durable_task argument {path} is a live object ({type(value).__module__}."
+        f"{type(value).__qualname__}) — clients, connections and other handles must not "
+        "cross the durable-task boundary. Construct them INSIDE the task body and pass "
+        "plain data (str/int/float/bool/bytes/list/dict/pydantic model) in."
+    )
+
+
+@overload
+def durable_task[F: Callable[..., Any]](fn: F) -> F: ...
+@overload
+def durable_task(
+    *, name: str | None = None, retry_policy: RetryPolicy | None = None
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]: ...
+
+
+def durable_task(
+    fn: Callable[..., Any] | None = None,
+    *,
+    name: str | None = None,
+    retry_policy: RetryPolicy | None = None,
+) -> Any:
+    """Mark a paid / side-effecting step durable: memoized across crash-resume.
+
+    Thin, validated wrapper over ``langgraph.func.task`` — a resumed run replays the
+    completed call's persisted result instead of re-executing it. Call it from inside
+    a graph node (sync or async; ``await fn(...)`` / ``fn(...).result()``). Arguments
+    are validated per call (see :func:`_assert_memo_safe`); the result must be
+    checkpoint-serialisable, exactly like node state.
+
+    :param name: memo identity (defaults to the function name). Renaming a durable
+        task orphans in-flight runs' memoized results — treat the name as a contract.
+    :param retry_policy: forwarded to ``langgraph.func.task`` (transient in-process
+        retries; distinct from the platform's crash-resume).
+    """
+
+    def decorate(f: Callable[..., Any]) -> Callable[..., Any]:
+        inner = task(name=name or f.__name__, retry_policy=retry_policy)(f)
+
+        def call(*args: Any, **kwargs: Any) -> Any:
+            for i, a in enumerate(args):
+                _assert_memo_safe(a, f"#{i}")
+            for k, a in kwargs.items():
+                _assert_memo_safe(a, k)
+            return inner(*args, **kwargs)
+
+        call.__name__ = name or f.__name__
+        call.__doc__ = f.__doc__
+        call.__wrapped__ = f  # type: ignore[attr-defined]
+        return call  # type: ignore[return-value]
+
+    return decorate(fn) if fn is not None else decorate
+
+
+def idempotency_key(thread_id: str, node: str, call: str) -> str:
+    """Deterministic dedup key for a mutating call: stable across crash-resume retries.
+
+    Same logical call → same key on every replay, so the downstream system can drop
+    the duplicate (memoization alone cannot help when the crash lands INSIDE the
+    mutation). ``thread_id`` comes from the node's ``config["configurable"]["thread_id"]``;
+    ``node`` is the node name; ``call`` identifies the call site + its business identity
+    (e.g. ``f"refund:{order_id}"``) — include a loop index if the node issues several.
+    """
+    joined = "\x1f".join((thread_id, node, call))
+    return hashlib.sha256(joined.encode("utf-8")).hexdigest()

keystone/agent_sdk/hitl.py

@@ -0,0 +1,43 @@
+"""Human-in-the-loop authoring primitive (M3.4 — FDP-3335 / US-4c).
+
+``request_approval`` pauses the graph via LangGraph ``interrupt()`` and returns the
+approver's decision when the run resumes (``Command(resume=<decision>)`` — the platform's
+respond API sends it in M3.5). The run parks as ``awaiting_human``; days may pass — the
+checkpointer keeps the thread alive and the worker holds NO process meanwhile.
+
+Rules (enforced by review; violations = double side-effects or lost pauses):
+
+* **Call it EARLY in the node.** On resume the whole node body RE-RUNS from the top up to
+  the interrupt point — everything before ``request_approval`` must be idempotent (wrap
+  paid steps in ``@durable_task``; give mutations ``idempotency_key``).
+* **ONE ``request_approval`` per node/run (v1).** Multiple or parallel interrupts are out
+  of scope: upstream langgraph#6208 re-runs a two-interrupt node after one resume, and the
+  platform enforces a single OPEN pending per run (partial unique index).
+* The payload must be plain JSON-able data — it is stored in ``hitl_pending`` and shown to
+  the approver verbatim.
+
+Usage::
+
+    from keystone.agent_sdk import request_approval
+
+    async def escalate(state: State) -> dict:
+        decision = request_approval({"kind": "escalation", "draft": state["reply"]})
+        if not decision.get("approved"):
+            return {"reply": decision.get("note", "Escalation rejected.")}
+        ...
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from langgraph.types import interrupt
+
+
+def request_approval(payload: dict[str, Any]) -> Any:
+    """Pause the run for human approval; returns the approver's decision on resume.
+
+    :param payload: JSON-able approval request (draft, kind, …) shown to the approver.
+    :returns: whatever the approver responds with (the platform sends a dict).
+    """
+    return interrupt(payload)

keystone/agent_sdk/loader.py

@@ -0,0 +1,62 @@
+"""Load an agent's compiled LangGraph from its manifest entrypoint (FDP-3120).
+
+Backs ``keystone agent run`` (the CLI local loop) and is available to any host needing a
+compiled graph from an ``entrypoint`` string. The module is resolved relative to ``project_dir``
+(the agent project root) — mirroring :func:`keystone.agent_sdk.validate`'s import model — so a
+checked-out agent project runs with no install. No checkpointer here (local/dev); the durable
+runtime compiles with its own checkpointer (agent-runtime, FDP-3115).
+"""
+
+from __future__ import annotations
+
+import importlib
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing import Any
+
+
+class GraphLoadError(Exception):
+    """An agent entrypoint could not be imported / built / compiled into a graph."""
+
+
+def load_graph(entrypoint: str, project_dir: str | Path | None = None) -> Any:
+    """Import ``module.path:factory``, call the factory, and return the **compiled** graph.
+
+    :param entrypoint: ``"module.path:factory"`` (the manifest's entrypoint).
+    :param project_dir: agent project root prepended to ``sys.path`` for the import (removed
+        afterwards). ``None`` → rely on the current ``sys.path``.
+    :raises GraphLoadError: malformed entrypoint / unimportable module / missing-or-uncallable
+        factory / a graph that fails to build or compile.
+    """
+    module_name, sep, factory_name = entrypoint.partition(":")
+    if sep != ":" or not module_name.strip() or not factory_name.strip():
+        raise GraphLoadError(f"invalid entrypoint {entrypoint!r} (expected 'module.path:factory')")
+
+    added: str | None = None
+    if project_dir is not None:
+        resolved = str(Path(project_dir).resolve())
+        if resolved not in sys.path:
+            sys.path.insert(0, resolved)
+            added = resolved
+    try:
+        try:
+            module = importlib.import_module(module_name)
+        except Exception as exc:  # ModuleNotFoundError + any import-time error
+            raise GraphLoadError(f"cannot import entrypoint module {module_name!r}: {exc}") from exc
+
+        factory = getattr(module, factory_name, None)
+        if not callable(factory):
+            raise GraphLoadError(f"entrypoint factory {factory_name!r} not found or not callable in {module_name!r}")
+
+        try:
+            graph = factory()
+        except Exception as exc:
+            raise GraphLoadError(f"entrypoint {entrypoint!r} failed to build: {exc}") from exc
+        # A LangGraph StateGraph must be compiled; a pre-compiled graph is returned as-is.
+        return graph.compile() if hasattr(graph, "compile") else graph
+    finally:
+        if added is not None:
+            sys.path.remove(added)

keystone/agent_sdk/manifest.py

@@ -0,0 +1,141 @@
+"""``agent.yaml`` manifest model — the single schema the SDK owns and shares across
+``init`` / ``validate`` / ``deploy`` (FDP-3072 §3.5b). Keys mirror visual-builder's
+``kind: Agent`` for stack convergence.
+
+Design rules baked in as validators:
+
+* ``entrypoint`` must be ``"module.path:factory"`` (the runtime graph-loader contract).
+* ``secrets`` carry **references only**, never inline values (a pod mounts its own
+  secrets by ref — proposal §5b). An inline value is a validation error.
+* ``extra="forbid"`` everywhere — an unknown/typo'd key fails fast rather than being
+  silently ignored.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class ResourceSpec(BaseModel):
+    """Deployment resources (→ agent-hub ``DeploymentEntity`` in M2)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    cpu: str = "500m"
+    memory: str = "512Mi"
+    replicas: int = Field(default=1, ge=0)
+    # Per-ATTEMPT execution budgets (D-M3-G, FDP-3332): sync in-request runs get
+    # ``timeout_seconds``; async (queued) runs get ``async_timeout_seconds``. NOT the queue
+    # wait, NOT the HITL wait (interrupt() returns immediately). Both are clamped by the
+    # platform cap (RT_MAX_RUN_SECONDS, default 7200) at the runtime.
+    timeout_seconds: int = Field(default=60, gt=0)
+    async_timeout_seconds: int = Field(default=600, gt=0)
+    # Canary / rollback are enforced by the agent-gateway in M2; declared here so the
+    # manifest schema is stable from M1.
+    canary_percentage: int | None = Field(default=None, ge=0, le=100)
+    auto_rollback_threshold: float | None = Field(default=None, ge=0)
+
+
+class HitlSpec(BaseModel):
+    """Approval-timeout policy (M3.6 / FDP-3337) for ``request_approval`` pauses.
+
+    The runtime denormalises ``timeout_seconds`` into ``hitl_pending.expires_at`` when the
+    run parks; the 5-minute recovery sweep then applies ``on_timeout``:
+
+    * ``"expire"`` (default) — the pending and the run both become terminal ``expired``.
+    * ``"reject"`` — the run resumes with ``{"approved": False, "timed_out": True}``, so
+      it flows the graph's NORMAL rejection branch (write one — don't assume approval).
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    timeout_seconds: int = Field(default=259200, gt=0)  # 72h
+    on_timeout: Literal["expire", "reject"] = "expire"
+    # Who may answer this agent's approvals (platform user ids — the portal identity).
+    # EMPTY (default) = anyone in the run's entity+workspace (the accepted v1 behavior).
+    # Non-empty = respond is rejected with 403 RT_HITL_FORBIDDEN for anyone else.
+    approvers: list[str] = Field(default_factory=list)
+
+
+class Dependencies(BaseModel):
+    """Building-block services + models + knowledge bases the agent needs (preflighted for quota/RBAC)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    services: list[str] = Field(default_factory=list)
+    models: list[str] = Field(default_factory=list)
+    # FDP-3072 P2 (ACL auto-grant): the KBs this agent queries, declared EXPLICITLY here rather than
+    # buried in freeform `config` env — so agent-hub can grant `knowledge-base:query` per-KB at
+    # publish (least-privilege) instead of over-granting at the workspace level. Optional: an agent
+    # with no KB (pure-LLM) leaves it empty and simply gets no KB grant. Values are KB UUIDs.
+    knowledge_bases: list[str] = Field(default_factory=list)
+
+
+class Identity(BaseModel):
+    """The agent's runtime identity scopes (provisioned by agent-hub at deploy)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    scopes: list[str] = Field(default_factory=list)
+
+
+class SecretRef(BaseModel):
+    """A secret **reference** (never a value). ``ref`` is a URI like ``aws-sm://kv/api-key``."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    ref: str
+
+    @field_validator("ref")
+    @classmethod
+    def _must_be_a_reference(cls, v: str) -> str:
+        if "://" not in v:
+            raise ValueError(
+                "secret 'ref' must be a reference URI (e.g. 'aws-sm://kv/api-key'), never an inline secret value"
+            )
+        return v
+
+
+class AgentManifest(BaseModel):
+    """The parsed ``agent.yaml``."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    workspace: str
+    framework: str = "langgraph@1"
+    entrypoint: str  # "module.path:factory"
+    runtime: str = "python3.12"
+    resources: ResourceSpec = Field(default_factory=ResourceSpec)
+    hitl: HitlSpec = Field(default_factory=HitlSpec)
+    io_schema: dict[str, Any] = Field(default_factory=dict)
+    dependencies: Dependencies = Field(default_factory=Dependencies)
+    tools: list[str] = Field(default_factory=list)
+    guardrails: list[str] = Field(default_factory=list)
+    identity: Identity = Field(default_factory=Identity)
+    secrets: list[SecretRef] = Field(default_factory=list)
+    # Per-agent config the DEV owns — injected as environment variables into the agent's pod
+    # (per-version, immutable) so the agent's code reads it via ``os.environ`` (e.g. a KB id or a
+    # model name). Keys are env-var names, values are strings. NOT for secrets — those go in
+    # ``secrets`` as references. Replaces stuffing per-agent values into the shared runtime
+    # ConfigMap (FDP-3306).
+    config: dict[str, str] = Field(default_factory=dict)
+
+    @field_validator("entrypoint")
+    @classmethod
+    def _entrypoint_shape(cls, v: str) -> str:
+        module, _, factory = v.partition(":")
+        if v.count(":") != 1 or not module.strip() or not factory.strip():
+            raise ValueError("entrypoint must be 'module.path:factory' (exactly one ':')")
+        return v
+
+
+def load_manifest(path: str | Path) -> AgentManifest:
+    """Load + validate an ``agent.yaml`` from disk into an :class:`AgentManifest`."""
+    data = yaml.safe_load(Path(path).read_text()) or {}
+    return AgentManifest.model_validate(data)

keystone/agent_sdk/provenance.py

@@ -0,0 +1,109 @@
+"""Where the deployed source came from — git commit + clean/dirty (deploy provenance).
+
+``create_bundle`` packages the **working directory**, not a git ref. That is deliberate (a dev can
+deploy without pushing), but it means "what is running in dev?" has no answer beyond a content hash:
+the same `bundle_sha256` tells you two uploads were identical, never which commit produced them, and
+nothing at all if the tree had uncommitted edits. LangSmith gets this for free by building from a git
+repo; we have to record it ourselves. This module is the recording half.
+
+Deliberately NOT written into the bundle. ``create_bundle``'s hash is a pure function of the source —
+that property is what makes a re-deploy dedupe to the existing version — and a provenance file inside
+the tar would make the same code hash differently from two commits. So it travels beside the upload.
+
+Everything here fails **soft**: a project that is not a git repo, a repo with no commits, a missing
+git binary, or a hung index lock all yield ``None``. Provenance is metadata; refusing to deploy
+without it would break the "scaffold and ship" path the templates advertise.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess  # noqa: S404 — git plumbing, fixed argv, never shell=True  # nosec B404
+from dataclasses import dataclass
+from pathlib import Path
+
+# git can block on an index.lock held by another process; a deploy must not hang on metadata.
+_GIT_TIMEOUT_S = 5.0
+
+# A branch name is unbounded in git but this ends up in a jsonb column, so cap it here rather than
+# letting the server be the only guard.
+_MAX_BRANCH_LEN = 255
+
+
+@dataclass(frozen=True)
+class SourceProvenance:
+    """The commit the bundle was built from, and whether the tree matched it.
+
+    ``dirty`` is the load-bearing field. A clean tree means the bundle is reproducible from
+    ``commit``; a dirty one means it is **not**, and no amount of commit-pinning recovers it. That is
+    the case worth warning about, because it is the one where "which code is running?" becomes
+    unanswerable after the fact.
+    """
+
+    commit: str
+    dirty: bool
+    branch: str | None = None
+
+    def as_payload(self) -> dict[str, object]:
+        """The wire form sent alongside the bundle upload."""
+        out: dict[str, object] = {"commit": self.commit, "dirty": self.dirty}
+        if self.branch:
+            out["branch"] = self.branch
+        return out
+
+    def summary(self) -> str:
+        """One-line human form, e.g. ``a1b2c3d (main, dirty)``."""
+        bits = [self.branch] if self.branch else []
+        if self.dirty:
+            bits.append("dirty")
+        suffix = f" ({', '.join(bits)})" if bits else ""
+        return f"{self.commit[:7]}{suffix}"
+
+
+def detect(project_dir: str | Path) -> SourceProvenance | None:
+    """Best-effort provenance for ``project_dir``, or ``None`` when it cannot be determined."""
+    root = Path(project_dir)
+    if _git(root, "rev-parse", "--is-inside-work-tree") != "true":
+        return None
+    commit = _git(root, "rev-parse", "HEAD")
+    if not commit:
+        return None  # a repo with no commits yet — nothing to pin to
+
+    # Scoped to THIS directory (`-- .`), not the whole repo: an agent project can live inside a
+    # monorepo, and unrelated edits elsewhere say nothing about whether this bundle is reproducible.
+    # `--porcelain` honours .gitignore, so an ignored file (.env) correctly does not mark it dirty,
+    # while an untracked non-ignored file does — that file IS packaged, so the tree really is not
+    # reproducible from the commit.
+    status = _git(root, "status", "--porcelain", "--", ".")
+    branch = _git(root, "rev-parse", "--abbrev-ref", "HEAD")
+    if branch == "HEAD":  # detached — no name to report
+        branch = None
+    return SourceProvenance(
+        commit=commit,
+        dirty=bool(status),
+        branch=branch[:_MAX_BRANCH_LEN] if branch else None,
+    )
+
+
+def _git(cwd: Path, *args: str) -> str | None:
+    """Run one git plumbing command in ``cwd``; ``None`` on any failure. Never raises."""
+    # Absolute path, resolved from PATH at call time. A partial argv[0] is a PATH-injection
+    # foothold, and resolving here keeps the function self-contained so a test can change PATH.
+    # Binary missing → the same soft failure as every other error path in this module.
+    git = shutil.which("git")
+    if git is None:
+        return None
+    try:
+        # Fixed argv, never shell=True, cwd is caller-controlled only.
+        proc = subprocess.run(  # noqa: S603  # nosec B603
+            [git, *args],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            timeout=_GIT_TIMEOUT_S,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        # No git binary, cwd vanished, or the call timed out on a lock.
+        return None
+    return proc.stdout.strip() if proc.returncode == 0 else None

keystone/agent_sdk/tracing.py

@@ -0,0 +1,100 @@
+"""GenAI client spans + trace propagation (FDP-3436 / spike Q3).
+
+``GatewayClient`` speaks plain httpx (OpenAI-compat REST, not the ``openai`` client), so
+NO auto-instrumentor sees the platform's LLM calls — the SDK emits the spans itself, with
+the ``gen_ai.*`` semconv attributes the observability redactor whitelists (token counts,
+models). Depends on ``opentelemetry-api`` ONLY: without a configured provider (local
+``keystone agent run``), every span here is a no-op — zero config, zero overhead. The
+agent-runtime harness installs the real provider at pod boot (``observability.tracing``).
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any
+
+from opentelemetry import trace
+from opentelemetry.trace import SpanKind
+from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+# ProxyTracer: bound lazily to whatever provider the host process installs later.
+_tracer = trace.get_tracer("keystone.agent_sdk")
+_propagator = TraceContextTextMapPropagator()
+
+
+@contextmanager
+def genai_span(operation: str, model: str) -> Iterator[Any]:
+    """CLIENT span for one llm-gateway call, named per GenAI semconv (``chat gemma``).
+
+    Typed as a plain SPAN for Langfuse, not a generation (FDP-3663). Langfuse infers
+    "generation" from any span carrying a ``model`` attribute, so this span — which describes the
+    HTTP hop to the gateway — was being counted as a second generation alongside LiteLLM's real
+    one. Measured on dev: one LLM call produced two GENERATION observations both reporting
+    ``41 → 129`` tokens. Cost stayed correct (this span's cost is 0), but any consumer summing
+    tokens across generations would double them.
+
+    ``langfuse.observation.type`` is the documented override, so the ``gen_ai.*`` semconv
+    attributes stay — dropping them to dodge the inference would throw away correct OTel data and
+    the token counts a non-Langfuse backend reads.
+
+    Trade-off worth knowing: LiteLLM's callback is now the ONLY generation for the call. If the
+    gateway's Langfuse callback is ever disabled, the trace keeps this span (with its ``gen_ai.*``
+    usage attributes) but loses the generation view.
+    """
+    with _tracer.start_as_current_span(f"{operation} {model}", kind=SpanKind.CLIENT) as span:
+        span.set_attribute("gen_ai.operation.name", operation)
+        span.set_attribute("gen_ai.system", "keystone.llm-gateway")
+        span.set_attribute("gen_ai.request.model", model)
+        span.set_attribute("langfuse.observation.type", "span")
+        yield span
+
+
+def link_generation(span: Any, body: dict[str, Any]) -> None:
+    """Tell llm-gateway which observation LiteLLM's generation belongs UNDER (FDP-3663).
+
+    The gateway forwards ``body.metadata`` into the LiteLLM metadata
+    (``build_litellm_metadata(extra=body.metadata)``), and LiteLLM's Langfuse callback nests its
+    generation under ``parent_observation_id``. Without it the generation attaches to the trace
+    ROOT as a sibling of ``agent.run``, so its cost never rolls up into the agent's own span —
+    measured on dev: the trace root showed ``$0.002402`` while ``agent.run`` showed ``$0.000000``.
+
+    Parented to the CLIENT span, i.e. the generation becomes a child of ``chat <model>``, because
+    that is the real nesting: our span covers the HTTP call to the gateway and the LLM call happens
+    inside it (durations agree — a 4.79s generation inside a 5.09s ``chat``). Making them siblings
+    would claim the two ran side by side.
+
+    ``setdefault`` twice on purpose: a caller passing its own ``metadata`` (or its own
+    ``parent_observation_id``) keeps it. No tracer / non-recording span → span id 0 → no-op, so a
+    local ``keystone agent run`` sends no metadata at all.
+    """
+    try:
+        span_id = span.get_span_context().span_id
+    except Exception:  # pragma: no cover — defensive: tracing must never break a call
+        return
+    if not span_id:
+        return
+    meta = body.setdefault("metadata", {})
+    if isinstance(meta, dict):
+        meta.setdefault("parent_observation_id", format(span_id, "016x"))
+
+
+def record_usage(span: Any, response: dict[str, Any]) -> None:
+    """Stamp token usage from an OpenAI-compat response onto the span (safe no-op on
+    non-recording spans / absent ``usage``)."""
+    usage = response.get("usage") or {}
+    if "prompt_tokens" in usage:
+        span.set_attribute("gen_ai.usage.input_tokens", int(usage["prompt_tokens"]))
+    if "completion_tokens" in usage:
+        span.set_attribute("gen_ai.usage.output_tokens", int(usage["completion_tokens"]))
+    if response.get("model"):
+        span.set_attribute("gen_ai.response.model", str(response["model"]))
+
+
+def inject_traceparent(headers: dict[str, str]) -> dict[str, str]:
+    """Add the W3C ``traceparent`` for the CURRENT span context to outbound headers —
+    agent → rag/llm-gateway hops join the run's trace. No active span → no-op."""
+    _propagator.inject(headers)
+    return headers

keystone/agent_sdk/validate.py

@@ -0,0 +1,69 @@
+"""``validate()`` — check an ``agent.yaml`` is well-formed and its entrypoint is
+importable, *without* deploying. Backs ``keystone agent validate`` (FDP-3120) and the
+deploy preflight (M2).
+
+The entrypoint module is resolved **relative to the manifest's directory** (the agent
+project root), so ``entrypoint: rag_qa.graph:make_graph`` imports from the project the
+manifest lives in — no install required.
+"""
+
+from __future__ import annotations
+
+import importlib
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from pydantic import ValidationError
+
+from .manifest import AgentManifest, load_manifest
+
+
+@dataclass
+class ValidationResult:
+    """Outcome of :func:`validate`. ``ok`` is ``True`` only when ``errors`` is empty."""
+
+    ok: bool
+    errors: list[str] = field(default_factory=list)
+    manifest: AgentManifest | None = None
+
+
+def validate(manifest_path: str | Path) -> ValidationResult:
+    """Validate the manifest at ``manifest_path`` + that its entrypoint is importable."""
+    path = Path(manifest_path)
+    if not path.is_file():
+        return ValidationResult(ok=False, errors=[f"manifest not found: {path}"])
+
+    try:
+        manifest = load_manifest(path)
+    except ValidationError as e:
+        return ValidationResult(ok=False, errors=[f"manifest invalid: {e}"])
+    except Exception as e:  # noqa: BLE001 — surface any YAML/read error as a validation error
+        return ValidationResult(ok=False, errors=[f"manifest unreadable: {e}"])
+
+    errors = _check_entrypoint_importable(manifest.entrypoint, path.resolve().parent)
+    return ValidationResult(ok=not errors, errors=errors, manifest=manifest)
+
+
+def _check_entrypoint_importable(entrypoint: str, project_dir: Path) -> list[str]:
+    module_name, _, factory_name = entrypoint.partition(":")
+    project_dir_str = str(project_dir)
+    added = project_dir_str not in sys.path
+    if added:
+        sys.path.insert(0, project_dir_str)
+    try:
+        module = importlib.import_module(module_name)
+    except ModuleNotFoundError as e:
+        return [f"entrypoint module '{module_name}' is not importable: {e}"]
+    except Exception as e:  # noqa: BLE001 — an import-time error is still a bad entrypoint
+        return [f"entrypoint module '{module_name}' raised on import: {e}"]
+    finally:
+        if added:
+            sys.path.remove(project_dir_str)
+
+    factory = getattr(module, factory_name, None)
+    if factory is None:
+        return [f"entrypoint factory '{factory_name}' not found in module '{module_name}'"]
+    if not callable(factory):
+        return [f"entrypoint '{entrypoint}' is not callable"]
+    return []

keystone_agent_sdk-0.3.0.dist-info/METADATA

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: keystone-agent-sdk
+Version: 0.3.0
+Summary: Keystone pro-code agent SDK — LangGraph authoring primitives (StateGraph, @tool), the agent.yaml manifest model, and validate(). FR-04 / FDP-3072 (M1).
+Requires-Python: >=3.12
+Requires-Dist: langgraph<2,>=1
+Requires-Dist: langchain-core<2,>=0.3
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: pyyaml<7,>=6
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: keystone-request-context<0.4,>=0.3
+Requires-Dist: opentelemetry-api<2,>=1.28
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8; extra == "dev"
+Requires-Dist: pytest-cov<7,>=6; extra == "dev"
+Requires-Dist: ruff==0.15.15; extra == "dev"
+Requires-Dist: opentelemetry-sdk<2,>=1.28; extra == "dev"

keystone_agent_sdk-0.3.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+keystone/agent_sdk/__init__.py,sha256=2UDvZTzaWCgIgp0BmSBOA9xW0Xlmstu4UgGqs8Qha_s,1945
+keystone/agent_sdk/bundle.py,sha256=BM8CcWVV3MYqR8YXnK3R66b1iGdFJdthJb5dGJkgP1Y,7998
+keystone/agent_sdk/durable.py,sha256=Eq6Op_IZ0zQnIkkvrKvdzsTFJodMrrZNmuOsx6OQ9YI,7042
+keystone/agent_sdk/hitl.py,sha256=ZY3LXzq_1UaurvTLScz7zKAaxWPlt5QWBqEknYGuEmQ,1892
+keystone/agent_sdk/loader.py,sha256=BgAdreekbgMSsMaGfCNOA1YLSopDwISCtAwoKbl8yKA,2734
+keystone/agent_sdk/manifest.py,sha256=W33hdnPNWYpEiqZDb_4pQnGIik8vIexqvXcsAVu2LTk,6006
+keystone/agent_sdk/provenance.py,sha256=2xqgyajc_Vy4_7uJUiDUuYjISC-4wWkWjdp9jbcPZ4U,4938
+keystone/agent_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+keystone/agent_sdk/tracing.py,sha256=8fwXAJf0e7JJuldtfraynxVPvoel6wd8IkVUHnrOLDE,5107
+keystone/agent_sdk/validate.py,sha256=snMxyYQQW8RBg0EneNBNHvmJnIhA1_Jq4Gsn17vdnUo,2644
+keystone/agent_sdk/clients/__init__.py,sha256=j62baSqK-aKbORgSIHTnIzkfyZO_F18LTwJ9TBg7TqQ,882
+keystone/agent_sdk/clients/_base.py,sha256=SNyJsa74E89p-Qy7-cquDeARUhrcZpOFqj78wpywb5Q,2256
+keystone/agent_sdk/clients/_errors.py,sha256=8Lc4fzgpXRDN6xEhFlmPLHzCg0u4Y9ZkcYpuIrwTARE,3347
+keystone/agent_sdk/clients/gateway.py,sha256=kBOOBxHCxQ31iabiMzZ9T25OobGSAJwN-uzdz7EaeYQ,2243
+keystone/agent_sdk/clients/rag.py,sha256=UL3_OGi6V2dMl6rMwTD5c17bW-r7zvZMTZcXB5_HXyc,1159
+keystone_agent_sdk-0.3.0.dist-info/METADATA,sha256=VleY9HOJjbm4C568SyQrLjDHzF2J8iCaxtT0p1D3pdI,713
+keystone_agent_sdk-0.3.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+keystone_agent_sdk-0.3.0.dist-info/top_level.txt,sha256=XS9DabbjrYNyRjQpLiI8n1RiT-5pV3BRO7CLSCg68ZY,9
+keystone_agent_sdk-0.3.0.dist-info/RECORD,,

keystone_agent_sdk-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

keystone_agent_sdk-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+keystone