keystone-agent-sdk 0.3.0__tar.gz

keystone_agent_sdk-0.3.0/PKG-INFO

@@ -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/__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-0.3.0/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-0.3.0/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-0.3.0/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-0.3.0/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-0.3.0/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-0.3.0/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-0.3.0/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()