agentcore-cli 0.31.1__py3-none-any.whl

agentcore/operations/dev/load_dev_env.py

@@ -0,0 +1,26 @@
+"""Port of operations/dev/load-dev-env.ts."""
+
+from dataclasses import dataclass
+from typing import Any
+
+from agentcore.lib.schemas.io.path_resolver import find_config_root
+from agentcore.lib.utils.env import read_env_file
+from agentcore.operations.dev.gateway_env import get_gateway_env_vars
+from agentcore.operations.dev.memory_env import get_memory_env_vars
+from agentcore.operations.dev.payment_env import get_payment_env_vars
+
+
+@dataclass
+class DevEnv:
+    env_vars: dict[str, str]
+    """Deployed-state (gateway + memory + payment) vars first, then .env overrides."""
+    deployed_memory_count: int
+
+
+def load_dev_env(working_dir: str, runtime: Any | None = None) -> DevEnv:
+    config_root = find_config_root(working_dir)
+    dot_env = read_env_file(config_root) if config_root else {}
+    gateway = get_gateway_env_vars()
+    memory = get_memory_env_vars()
+    payment = get_payment_env_vars(runtime)
+    return DevEnv(env_vars={**gateway, **memory, **payment, **dot_env}, deployed_memory_count=len(memory))

agentcore/operations/dev/memory_env.py

@@ -0,0 +1,19 @@
+"""Port of operations/dev/memory-env.ts."""
+
+from agentcore.lib.schemas.io.config_io import ConfigIO
+
+
+def get_memory_env_vars() -> dict[str, str]:
+    """``MEMORY_<NAME>_ID`` for every deployed memory across all targets."""
+    env: dict[str, str] = {}
+    try:
+        state = ConfigIO().read_deployed_state()
+        for target in (state.targets or {}).values():
+            resources = target.resources if target else None
+            for name, memory in ((resources.memories if resources else None) or {}).items():
+                if not memory.memory_id:
+                    continue
+                env[f"MEMORY_{name.upper().replace('-', '_')}_ID"] = memory.memory_id
+    except Exception:  # noqa: BLE001 - no deployed state: skip, as upstream
+        pass
+    return env

agentcore/operations/dev/otel/__init__.py

@@ -0,0 +1,5 @@
+"""Local OTLP collector for `agentcore dev` (port of operations/dev/otel)."""
+
+from agentcore.operations.dev.otel.collector import OtelCollector, start_otel_collector
+
+__all__ = ["OtelCollector", "start_otel_collector"]

agentcore/operations/dev/otel/collector.py

@@ -0,0 +1,234 @@
+"""Port of operations/dev/otel/collector.ts: in-process OTLP/HTTP receiver for dev mode.
+
+Accepts spans (POST /v1/traces) and logs (POST /v1/logs) as OTLP protobuf or JSON, appends them
+to per-trace JSON Lines files under ``<persistDir>/otlp/`` and serves them back flattened. All reads
+go to disk; there is no in-memory store.
+"""
+
+import json
+import os
+import re
+import threading
+import time
+from collections.abc import Callable
+from datetime import UTC, datetime
+from typing import Any
+
+from agentcore.operations.dev._server import Request, Response, js_dumps, make_server
+from agentcore.operations.dev.otel.transforms import build_trace_detail, extract_first_trace_info, extract_trace_meta
+from agentcore.operations.dev.utils import find_available_port
+
+DEFAULT_OTLP_PORT = 4318
+OTLP_SUBDIR = "otlp"
+OTLP_EXT = ".otlp.jsonl"
+
+OnLog = Callable[[str, str], None]
+
+
+def _iso(ms: int) -> str:
+    dt = datetime.fromtimestamp(ms / 1000, tz=UTC)
+    return dt.strftime("%Y-%m-%dT%H:%M:%S.") + f"{dt.microsecond // 1000:03d}Z"
+
+
+def _decode_protobuf(raw: bytes, kind: str) -> dict[str, Any]:
+    """Decode an OTLP protobuf request into the same JSON shape protobufjs' toJSON produces
+    (camelCase fields, int64 as strings, enums as names, bytes as base64, defaults omitted)."""
+    from google.protobuf.json_format import MessageToDict
+
+    if kind == "traces":
+        from opentelemetry.proto.collector.trace.v1.trace_service_pb2 import ExportTraceServiceRequest
+
+        message: Any = ExportTraceServiceRequest()
+    else:
+        from opentelemetry.proto.collector.logs.v1.logs_service_pb2 import ExportLogsServiceRequest
+
+        message = ExportLogsServiceRequest()
+    message.ParseFromString(raw)
+    return MessageToDict(message)
+
+
+class OtelCollector:
+    def __init__(self, on_log: OnLog | None = None, persist_traces_dir: str | None = None):
+        self.on_log = on_log
+        self.persist_dir = persist_traces_dir
+        self.port = 0
+        self._server = None
+        self._thread: threading.Thread | None = None
+
+    def _log(self, level: str, message: str) -> None:
+        if self.on_log:
+            self.on_log(level, message)
+
+    def start(self, port: int | None = None) -> int:
+        """Bind 127.0.0.1 on the first free port from 4318 (or ``port``); returns the port."""
+        self.port = port if port is not None else find_available_port(DEFAULT_OTLP_PORT)
+        self._server = make_server("127.0.0.1", self.port, self._handle_request)
+        self.port = self._server.server_address[1]
+        self._thread = threading.Thread(target=self._server.serve_forever, daemon=True)
+        self._thread.start()
+        self._log("info", f"OTEL collector listening on port {self.port}")
+        if self.persist_dir:
+            self._log("info", f"OTEL trace persistence enabled → {self.persist_dir}")
+        return self.port
+
+    def stop(self) -> None:
+        if self._server is not None:
+            self._server.shutdown()
+            self._server.server_close()
+            self._server = None
+
+    def get_port(self) -> int:
+        return self.port
+
+    # --- queries ----------------------------------------------------------------------------
+
+    def _otlp_dir(self) -> str | None:
+        return os.path.join(self.persist_dir, OTLP_SUBDIR) if self.persist_dir else None
+
+    def _files(self) -> list[str]:
+        otlp_dir = self._otlp_dir()
+        if not otlp_dir or not os.path.exists(otlp_dir):
+            return []
+        return [f for f in os.listdir(otlp_dir) if f.endswith(OTLP_EXT)]
+
+    def list_traces(
+        self, agent_name: str | None, start_time: float | None = None, end_time: float | None = None
+    ) -> dict[str, Any]:
+        otlp_dir = self._otlp_dir()
+        if not otlp_dir or not os.path.exists(otlp_dir):
+            return {"success": True, "traces": []}
+        now = int(time.time() * 1000)
+        start = start_time if start_time is not None else now - 12 * 60 * 60 * 1000
+        end = end_time if end_time is not None else now
+        traces: list[dict[str, Any]] = []
+        for name in self._files():
+            try:
+                spans, logs = self._read_trace_file(os.path.join(otlp_dir, name))
+                meta = extract_trace_meta(spans, logs)
+                if not meta["traceId"]:
+                    continue
+                if meta["lastSeen"] < start or meta["firstSeen"] > end:
+                    continue
+                if agent_name and meta["serviceName"] != agent_name:
+                    continue
+                traces.append(
+                    {
+                        "traceId": meta["traceId"],
+                        "timestamp": _iso(meta["lastSeen"]),
+                        "sessionId": meta["sessionId"],
+                        "spanCount": str(meta["spanCount"]),
+                        **build_trace_detail(spans, logs),
+                        "_sort": meta["lastSeen"],
+                    }
+                )
+            except Exception:  # noqa: BLE001 - skip malformed files, as upstream
+                continue
+        traces.sort(key=lambda t: t["_sort"], reverse=True)
+        for t in traces:
+            del t["_sort"]
+        return {"success": True, "traces": traces}
+
+    def get_trace_spans(self, _agent_name: str | None, trace_id: str) -> dict[str, Any]:
+        otlp_dir = self._otlp_dir()
+        not_found = {"success": False, "error": f"No trace data found for trace ID: {trace_id}"}
+        if not otlp_dir or not os.path.exists(otlp_dir):
+            return not_found
+        match = next((f for f in self._files() if trace_id in f), None)
+        if match is None:
+            return not_found
+        try:
+            spans, logs = self._read_trace_file(os.path.join(otlp_dir, match))
+            return {"success": True, **build_trace_detail(spans, logs)}
+        except Exception:  # noqa: BLE001
+            return {"success": False, "error": f"Failed to read trace data for trace ID: {trace_id}"}
+
+    # --- ingest -----------------------------------------------------------------------------
+
+    def _handle_request(self, req: Request, res: Response) -> None:
+        if req.method == "POST" and req.url in ("/v1/traces", "/v1/logs"):
+            kind = "traces" if req.url == "/v1/traces" else "logs"
+            try:
+                payload = self._decode_payload(req.read_body(), req.header("content-type") or "", kind)
+                self._persist_otlp(payload)
+                res.write_head(200, {"Content-Type": "application/json"})
+                res.end("{}")
+            except Exception as err:  # noqa: BLE001 - reported as 400, as upstream
+                label = "OTEL ingest error" if kind == "traces" else "OTEL log ingest error"
+                self._log("warn", f"{label}: {err}")
+                res.write_head(400, {"Content-Type": "application/json"})
+                error = "Invalid OTLP payload" if kind == "traces" else "Invalid OTLP logs payload"
+                res.end(js_dumps({"error": error}))
+            return
+        if req.method == "GET" and req.url == "/":
+            res.write_head(200, {"Content-Type": "application/json"})
+            res.end(js_dumps({"status": "ok"}))
+            return
+        self._log("warn", f"OTEL collector: unhandled {req.method} {req.url}")
+        res.write_head(404)
+        res.end()
+
+    def _decode_payload(self, raw: bytes, content_type: str, kind: str) -> dict[str, Any]:
+        if "application/json" in content_type:
+            parsed = json.loads(raw.decode("utf-8"))
+            if not isinstance(parsed, dict):
+                raise ValueError("OTLP JSON payload must be an object")
+            return parsed
+        return _decode_protobuf(raw, kind)
+
+    def _persist_otlp(self, data: dict[str, Any]) -> None:
+        otlp_dir = self._otlp_dir()
+        if not otlp_dir:
+            return
+        try:
+            os.makedirs(otlp_dir, exist_ok=True)
+            info = extract_first_trace_info(data)
+            trace_id = info.get("traceId")
+            if not trace_id:
+                return
+
+            def sanitize(val: str) -> str:
+                return re.sub(r"[^a-zA-Z0-9_-]", "_", val)
+
+            prefix = sanitize(info.get("serviceName") or "dev")
+            path = os.path.join(otlp_dir, f"{prefix}-{sanitize(trace_id)}{OTLP_EXT}")
+            with open(path, "a", encoding="utf-8") as f:
+                f.write(js_dumps(data) + "\n")
+        except Exception as err:  # noqa: BLE001
+            self._log("warn", f"Failed to persist OTLP: {err}")
+
+    def _read_trace_file(self, path: str) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+        spans: list[dict[str, Any]] = []
+        logs: list[dict[str, Any]] = []
+        with open(path, encoding="utf-8") as f:
+            for line in f.read().split("\n"):
+                if not line.strip():
+                    continue
+                try:
+                    entry = json.loads(line)
+                except ValueError:
+                    continue
+                if entry.get("resourceSpans"):
+                    spans.extend(entry["resourceSpans"])
+                if entry.get("resourceLogs"):
+                    logs.extend(entry["resourceLogs"])
+        return spans, logs
+
+
+def start_otel_collector(persist_traces_dir: str) -> tuple[OtelCollector, dict[str, str]]:
+    """Start a collector and return it with the OTEL env vars agents need to export to it."""
+    collector = OtelCollector(persist_traces_dir=persist_traces_dir)
+    port = collector.start()
+    env = os.environ
+    otel_env_vars = {
+        "OTEL_EXPORTER_OTLP_ENDPOINT": env.get("OTEL_EXPORTER_OTLP_ENDPOINT") or f"http://127.0.0.1:{port}",
+        "OTEL_EXPORTER_OTLP_PROTOCOL": env.get("OTEL_EXPORTER_OTLP_PROTOCOL") or "http/protobuf",
+        "OTEL_METRICS_EXPORTER": env.get("OTEL_METRICS_EXPORTER") or "none",
+        "AGENT_OBSERVABILITY_ENABLED": env.get("AGENT_OBSERVABILITY_ENABLED") or "true",
+        "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT": env.get(
+            "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"
+        )
+        or "true",
+        "OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED": env.get("OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED")
+        or "true",
+    }
+    return collector, otel_env_vars

agentcore/operations/dev/otel/transforms.py

@@ -0,0 +1,331 @@
+"""Port of operations/dev/otel/transforms.ts: OTLP metadata extraction and frontend shaping."""
+
+import base64
+import binascii
+import math
+import re
+import time
+from typing import Any
+
+_HEX = re.compile(r"^[0-9a-f]+$", re.IGNORECASE)
+
+
+def _now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def _js_number(value: Any) -> float | int | None:
+    """``Number(value)`` for OTLP int64 values (strings after the protobuf JSON roundtrip)."""
+    if isinstance(value, bool):
+        return int(value)
+    if isinstance(value, (int, float)):
+        return value
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        try:
+            number = float(value)
+        except (TypeError, ValueError):
+            return None
+        return None if math.isnan(number) else number
+
+
+def nano_to_ms(nano: Any) -> int:
+    if not nano:
+        return 0
+    try:
+        return int(nano) // 1_000_000
+    except (TypeError, ValueError):
+        try:
+            return math.floor(float(nano) / 1_000_000)
+        except (TypeError, ValueError):
+            return 0
+
+
+def hex_from_b64_or_string(val: str | None) -> str:
+    """Hex trace/span id from either a hex string or base64 (protobuf JSON roundtrip)."""
+    if not val:
+        return ""
+    if _HEX.match(val) and len(val) in (32, 16):
+        return val.lower()
+    try:
+        cleaned = re.sub(r"[^A-Za-z0-9+/=_-]", "", val).replace("-", "+").replace("_", "/")
+        cleaned += "=" * (-len(cleaned) % 4)
+        return base64.b64decode(cleaned).hex()
+    except (binascii.Error, ValueError):
+        return val
+
+
+def _get_attr_value(attrs: Any, key: str) -> str | None:
+    if not attrs:
+        return None
+    if isinstance(attrs, list):
+        attr = next((a for a in attrs if isinstance(a, dict) and a.get("key") == key), None)
+        value = (attr or {}).get("value")
+        if not value:
+            return None
+        if value.get("stringValue") is not None:
+            return value["stringValue"]
+        return str(value["intValue"]) if value.get("intValue") is not None else None
+    val = attrs.get(key) if isinstance(attrs, dict) else None
+    return val if isinstance(val, str) else None
+
+
+def _get_resource_attribute(resource: Any, key: str) -> str | None:
+    return _get_attr_value((resource or {}).get("attributes"), key)
+
+
+def extract_trace_meta(resource_spans: list[dict[str, Any]], resource_logs: list[dict[str, Any]]) -> dict[str, Any]:
+    """traceId, firstSeen/lastSeen (ms), sessionId, serviceName and span/log count."""
+    trace_id: str | None = None
+    first_seen = math.inf
+    last_seen = 0
+    session_id: str | None = None
+    service_name: str | None = None
+    span_count = 0
+
+    for rs in resource_spans:
+        if service_name is None:
+            service_name = _get_resource_attribute(rs.get("resource"), "service.name")
+        for ss in rs.get("scopeSpans") or []:
+            for span in ss.get("spans") or []:
+                span_count += 1
+                if trace_id is None:
+                    trace_id = hex_from_b64_or_string(span.get("traceId")) or None
+                start_ms = nano_to_ms(span.get("startTimeUnixNano"))
+                end_ms = nano_to_ms(span.get("endTimeUnixNano"))
+                if start_ms and start_ms < first_seen:
+                    first_seen = start_ms
+                if end_ms and end_ms > last_seen:
+                    last_seen = end_ms
+                if not session_id:
+                    attrs = span.get("attributes")
+                    session_id = _get_attr_value(attrs, "session.id") or _get_attr_value(attrs, "attributes.session.id")
+
+    for rl in resource_logs:
+        if service_name is None:
+            service_name = _get_resource_attribute(rl.get("resource"), "service.name")
+        for sl in rl.get("scopeLogs") or []:
+            for lr in sl.get("logRecords") or []:
+                span_count += 1
+                if trace_id is None:
+                    trace_id = hex_from_b64_or_string(lr.get("traceId")) or None
+                t = nano_to_ms(lr.get("timeUnixNano")) or nano_to_ms(lr.get("observedTimeUnixNano"))
+                if t and t < first_seen:
+                    first_seen = t
+                if t and t > last_seen:
+                    last_seen = t
+
+    now = _now_ms()
+    if first_seen == math.inf:
+        first_seen = now
+    if last_seen == 0:
+        last_seen = now
+    return {
+        "traceId": trace_id,
+        "firstSeen": int(first_seen),
+        "lastSeen": last_seen,
+        "sessionId": session_id,
+        "serviceName": service_name,
+        "spanCount": span_count,
+    }
+
+
+def extract_first_trace_info(data: dict[str, Any]) -> dict[str, str | None]:
+    for rs in data.get("resourceSpans") or []:
+        svc = _get_resource_attribute(rs.get("resource"), "service.name")
+        for ss in rs.get("scopeSpans") or []:
+            for span in ss.get("spans") or []:
+                if span.get("traceId"):
+                    return {"traceId": hex_from_b64_or_string(span["traceId"]), "serviceName": svc}
+    for rl in data.get("resourceLogs") or []:
+        svc = _get_resource_attribute(rl.get("resource"), "service.name")
+        for sl in rl.get("scopeLogs") or []:
+            for lr in sl.get("logRecords") or []:
+                if lr.get("traceId"):
+                    return {"traceId": hex_from_b64_or_string(lr["traceId"]), "serviceName": svc}
+    return {}
+
+
+_SPAN_KINDS = {
+    "SPAN_KIND_INTERNAL": 1,
+    "SPAN_KIND_SERVER": 2,
+    "SPAN_KIND_CLIENT": 3,
+    "SPAN_KIND_PRODUCER": 4,
+    "SPAN_KIND_CONSUMER": 5,
+}
+
+
+def _normalize_span_kind(kind: Any) -> int:
+    if isinstance(kind, bool):
+        return 0
+    if isinstance(kind, (int, float)):
+        return int(kind)
+    if isinstance(kind, str):
+        return _SPAN_KINDS.get(kind, 0)
+    return 0
+
+
+def is_meaningful_span(span: dict[str, Any]) -> bool:
+    """Drop ASGI/HTTP transport noise; keep GenAI, RPC, framework and tool spans."""
+    name = span.get("name") or ""
+    attrs = span.get("attributes") or {}
+    kind = _normalize_span_kind(span.get("kind"))
+    if name.endswith(" http send") or name.endswith(" http receive"):
+        return False
+    if attrs.get("asgi.event.type"):
+        return False
+    if any(k.startswith("gen_ai.") for k in attrs):
+        return True
+    if attrs.get("rpc.system") or attrs.get("rpc.method"):
+        return True
+    if any(h in name.lower() for h in ("strands", "bedrock", "langchain", "crewai", "autogen", "google_adk")):
+        return True
+    if name in ("tool_use", "tool_call") or attrs.get("tool.name"):
+        return True
+    if kind == 3 and (name in ("POST", "GET") or name.startswith("HTTP ")):
+        return False
+    if kind == 2 and name.startswith("POST /") and attrs.get("http.method"):
+        return False
+    return True
+
+
+def _scalar(v: dict[str, Any]) -> Any:
+    for key in ("stringValue", "intValue", "doubleValue", "boolValue"):
+        if v.get(key) is not None:
+            return v[key]
+    return None
+
+
+def flatten_attributes(attrs: Any) -> dict[str, Any] | None:
+    """OTLP key/value arrays → plain dict (already-flat dicts pass through)."""
+    if not attrs:
+        return None
+    if not isinstance(attrs, list):
+        return attrs
+    result: dict[str, Any] = {}
+    for attr in attrs:
+        value = attr.get("value")
+        if not value:
+            continue
+        key = attr.get("key")
+        if "stringValue" in value:
+            result[key] = value["stringValue"]
+        elif "intValue" in value:
+            result[key] = _js_number(value["intValue"])
+        elif "doubleValue" in value:
+            result[key] = value["doubleValue"]
+        elif "boolValue" in value:
+            result[key] = value["boolValue"]
+        elif (value.get("arrayValue") or {}).get("values"):
+            result[key] = [_scalar(v) for v in value["arrayValue"]["values"]]
+    return result
+
+
+def extract_any_value(val: Any) -> Any:
+    if not val or not isinstance(val, dict):
+        return val
+    if "stringValue" in val:
+        return val["stringValue"]
+    if "intValue" in val:
+        return _js_number(val["intValue"])
+    if "doubleValue" in val:
+        return val["doubleValue"]
+    if "boolValue" in val:
+        return val["boolValue"]
+    if isinstance(val.get("arrayValue"), dict):
+        return [extract_any_value(v) for v in val["arrayValue"].get("values") or []]
+    if isinstance(val.get("kvlistValue"), dict):
+        return {
+            kv.get("key"): extract_any_value(kv["value"]) if kv.get("value") else None
+            for kv in val["kvlistValue"].get("values") or []
+        }
+    return val
+
+
+def _drop_none(d: dict[str, Any]) -> dict[str, Any]:
+    """Mimic JSON.stringify dropping ``undefined`` properties."""
+    return {k: v for k, v in d.items() if v is not None}
+
+
+def build_trace_detail(
+    resource_spans: list[dict[str, Any]], resource_logs: list[dict[str, Any]]
+) -> dict[str, list[Any]]:
+    """Frontend-ready detail: flattened attributes, hex ids, noise spans filtered, log bodies unwrapped."""
+    filtered_spans = []
+    for rs in resource_spans:
+        resource = rs.get("resource")
+        scope_spans = []
+        for ss in rs.get("scopeSpans") or []:
+            spans = [
+                _drop_none(
+                    {
+                        **span,
+                        "traceId": hex_from_b64_or_string(span.get("traceId")),
+                        "spanId": hex_from_b64_or_string(span.get("spanId")),
+                        "parentSpanId": hex_from_b64_or_string(span.get("parentSpanId")),
+                        "attributes": flatten_attributes(span.get("attributes")),
+                    }
+                )
+                for span in ss.get("spans") or []
+            ]
+            spans = [s for s in spans if is_meaningful_span(s)]
+            if spans:
+                scope_spans.append(_drop_none({"scope": ss.get("scope"), "spans": spans}))
+        if scope_spans:
+            filtered_spans.append(
+                _drop_none(
+                    {
+                        "resource": _drop_none({"attributes": flatten_attributes(resource.get("attributes"))})
+                        if resource
+                        else None,
+                        "scopeSpans": scope_spans,
+                    }
+                )
+            )
+
+    flattened_logs = []
+    for rl in resource_logs:
+        resource = rl.get("resource")
+        scope_logs_raw = rl.get("scopeLogs")
+        if not scope_logs_raw:
+            continue
+        scope_logs = [
+            _drop_none(
+                {
+                    "scope": sl.get("scope"),
+                    "logRecords": [
+                        _drop_none(
+                            {
+                                **lr,
+                                "traceId": hex_from_b64_or_string(lr.get("traceId")),
+                                "spanId": hex_from_b64_or_string(lr.get("spanId")),
+                                "body": extract_any_value(lr["body"]) if lr.get("body") else None,
+                                "attributes": flatten_attributes(lr.get("attributes")),
+                            }
+                        )
+                        for lr in sl.get("logRecords") or []
+                    ]
+                    if sl.get("logRecords") is not None
+                    else None,
+                }
+            )
+            for sl in scope_logs_raw
+        ]
+        flattened_logs.append(
+            _drop_none(
+                {
+                    "resource": _drop_none({"attributes": flatten_attributes(resource.get("attributes"))})
+                    if resource
+                    else None,
+                    "scopeLogs": scope_logs,
+                }
+            )
+        )
+
+    return _drop_none(
+        {
+            "resourceSpans": filtered_spans or None,
+            "resourceLogs": flattened_logs or None,
+        }
+    )

agentcore/operations/dev/payment_env.py

@@ -0,0 +1,50 @@
+"""Port of operations/dev/payment-env.ts (+ primitives/payment-eligible.ts)."""
+
+from typing import Any
+
+from agentcore.lib.schemas.io.config_io import ConfigIO
+
+
+def is_payment_eligible_runtime(runtime: Any) -> bool:
+    """Payments only ship a shim for Python HTTP (Strands) runtimes; be conservative otherwise."""
+    protocol = getattr(runtime, "protocol", None)
+    if protocol and protocol != "HTTP":
+        return False
+    entrypoint = runtime.entrypoint if isinstance(getattr(runtime, "entrypoint", None), str) else ""
+    return entrypoint.split(":")[0].endswith(".py")
+
+
+def _js_bool(value: Any) -> str:
+    return ("true" if value else "false") if isinstance(value, bool) else str(value)
+
+
+def get_payment_env_vars(runtime: Any | None = None) -> dict[str, str]:
+    """Dev-mode payment env vars from deployed-state.json (mirrors the CDK stack's injection)."""
+    if runtime is not None and not is_payment_eligible_runtime(runtime):
+        return {}
+    env: dict[str, str] = {}
+    try:
+        state = ConfigIO().read_deployed_state()
+        for target in (state.targets or {}).values():
+            resources = target.resources if target else None
+            for name, payment in ((resources.payments if resources else None) or {}).items():
+                if not payment.manager_arn:
+                    continue
+                s = name.upper().replace("-", "_")
+                env[f"AGENTCORE_PAYMENT_{s}_MANAGER_ARN"] = payment.manager_arn
+                if payment.process_payment_role_arn:
+                    env[f"AGENTCORE_PAYMENT_{s}_PROCESS_PAYMENT_ROLE_ARN"] = payment.process_payment_role_arn
+                connectors = list((payment.connectors or {}).values())
+                if connectors:
+                    env[f"AGENTCORE_PAYMENT_{s}_CONNECTOR_ID"] = connectors[0].connector_id
+                if payment.auto_payment is not None:
+                    env[f"AGENTCORE_PAYMENT_{s}_AUTO_PAYMENT"] = _js_bool(payment.auto_payment)
+                if payment.payment_tool_allowlist:
+                    env[f"AGENTCORE_PAYMENT_{s}_TOOL_ALLOWLIST"] = ",".join(payment.payment_tool_allowlist)
+                if payment.network_preferences:
+                    env[f"AGENTCORE_PAYMENT_{s}_NETWORK_PREFERENCES"] = ",".join(payment.network_preferences)
+                if payment.authorizer_type == "CUSTOM_JWT":
+                    env[f"AGENTCORE_PAYMENT_{s}_AUTH_MODE"] = "bearer"
+    except Exception:  # noqa: BLE001 - no deployed state: skip, as upstream
+        pass
+    return env