agentcore-cli 0.31.1__py3-none-any.whl

agentcore/operations/jobs/shared/engine.py

@@ -0,0 +1,187 @@
+"""Job Engine (port of operations/jobs/shared/engine.ts).
+
+``create_job_engine(config_io)`` per call site. The engine owns persistence (start -> save) and
+the refresh-on-read lifecycle; commands stay thin. Start options are dicts keyed by the upstream
+(camelCase) option names; records are the camelCase dicts written to disk.
+
+Handlers are modules exposing ``create(opts, config_io)``, ``refresh(record)``, ``archive(record)``
+and, per type, ``stop``/``pause``/``resume``/``promote``/``debug``/``settle``. All return ``Ok``/``Err``
+(``settle`` returns the record).
+"""
+
+from collections.abc import Callable
+from concurrent.futures import ThreadPoolExecutor
+from functools import cmp_to_key
+from typing import Any
+
+from agentcore.aws import account
+from agentcore.lib import ConfigIO, JobNotFoundError
+from agentcore.lib.errors.types import to_error
+from agentcore.lib.result import Err, Ok
+from agentcore.operations.jobs.shared import storage
+from agentcore.operations.jobs.shared.constants import JOB_CAPABILITIES, JOB_TYPE_LABELS, is_terminal
+
+REFRESH_MAX_RETRIES = 3
+
+
+def _handlers() -> dict[str, Any]:
+    from agentcore.operations.jobs.ab_test import handler as ab_test
+    from agentcore.operations.jobs.batch_evaluation import handler as batch_evaluation
+    from agentcore.operations.jobs.insights import handler as insights
+    from agentcore.operations.jobs.recommendation import handler as recommendation
+
+    return {
+        "recommendation": recommendation,
+        "batch-evaluation": batch_evaluation,
+        "ab-test": ab_test,
+        "insights": insights,
+    }
+
+
+def _compare(a: dict[str, Any], b: dict[str, Any]) -> int:
+    """Newest first by createdAt, ties by id ascending (string comparison, as upstream)."""
+    ac, bc = a.get("createdAt") or "", b.get("createdAt") or ""
+    if bc > ac:
+        return 1
+    if bc < ac:
+        return -1
+    return -1 if a.get("id", "") < b.get("id", "") else 1
+
+
+class JobEngine:
+    def __init__(self, config_io: ConfigIO | None = None, handlers: dict[str, Any] | None = None):
+        self._config_io = config_io
+        self._handlers = handlers
+
+    @property
+    def config_io(self) -> ConfigIO:
+        if self._config_io is None:
+            self._config_io = ConfigIO()
+        return self._config_io
+
+    @property
+    def handlers(self) -> dict[str, Any]:
+        if self._handlers is None:
+            self._handlers = _handlers()
+        return self._handlers
+
+    # --- lifecycle helpers ------------------------------------------------------------
+
+    def _refresh_one(self, record: dict[str, Any]) -> dict[str, Any]:
+        if is_terminal(record):
+            return record
+        handler = self.handlers[record["type"]]
+        last_err: BaseException | None = None
+        for _ in range(REFRESH_MAX_RETRIES):
+            try:
+                result = handler.refresh(record)
+            except Exception as exc:  # noqa: BLE001 - treated like a failed Result
+                result = Err(to_error(exc))
+            if result.success:
+                updated = dict(result.value)
+                updated.pop("error", None)
+                storage.save_record(updated)
+                return updated
+            last_err = result.error
+        failed = {**record, "error": str(last_err)}
+        storage.save_record(failed)
+        return failed
+
+    def _settle_one(self, record: dict[str, Any]) -> dict[str, Any]:
+        settle = getattr(self.handlers[record["type"]], "settle", None)
+        if settle is None:
+            return record
+        try:
+            settled = settle(record, self.config_io)
+            if settled is not record:
+                storage.save_record(settled)
+            return settled
+        except Exception:  # noqa: BLE001 - settle failures leave the record unsynced (retried later)
+            return record
+
+    def _not_found(self, job_type: str, job_id: str) -> Err:
+        return Err(JobNotFoundError(f'{JOB_TYPE_LABELS[job_type]} "{job_id}" not found.'))
+
+    # --- public API -------------------------------------------------------------------
+
+    def start(self, job_type: str, opts: dict[str, Any]) -> Ok | Err:
+        try:
+            account.validate_aws_credentials()
+        except Exception as exc:  # noqa: BLE001
+            return Err(to_error(exc))
+        result = self.handlers[job_type].create(opts, self.config_io)
+        if result.success:
+            storage.save_record(result.value)
+        return result
+
+    def get(self, job_type: str, job_id: str) -> dict[str, Any] | None:
+        record = storage.load_record(job_type, job_id)
+        if record is None:
+            return None
+        return self._settle_one(self._refresh_one(record))
+
+    def list(self, *, type: str | None = None, limit: int | None = None, agent: str | None = None) -> list[dict]:
+        records = storage.list_records(type)
+        if len(records) > 1:
+            with ThreadPoolExecutor(max_workers=min(8, len(records))) as pool:
+                refreshed = list(pool.map(self._refresh_one, records))
+        else:
+            refreshed = [self._refresh_one(r) for r in records]
+        # Config-mutating settle steps run sequentially (no concurrent agentcore.json writes).
+        out = [self._settle_one(r) for r in refreshed]
+        if agent:
+            out = [r for r in out if r.get("agent") == agent]
+        out.sort(key=cmp_to_key(_compare))
+        if limit is not None:
+            out = out[:limit]
+        return out
+
+    def _with_record(self, job_type: str, job_id: str, fn: Callable[[dict[str, Any]], Ok | Err]) -> Ok | Err:
+        record = storage.load_record(job_type, job_id)
+        if record is None:
+            return self._not_found(job_type, job_id)
+        return fn(record)
+
+    def stop(self, job_type: str, job_id: str) -> Ok | Err:
+        def run(record: dict[str, Any]) -> Ok | Err:
+            result = self.handlers[job_type].stop(record)
+            if result.success:
+                storage.save_record({**record, "status": "STOPPING"})
+            return result
+
+        return self._with_record(job_type, job_id, run)
+
+    def _save_result(self, result: Ok | Err) -> Ok | Err:
+        if result.success:
+            storage.save_record(result.value)
+        return result
+
+    def pause(self, job_type: str, job_id: str) -> Ok | Err:
+        return self._with_record(job_type, job_id, lambda r: self._save_result(self.handlers[job_type].pause(r)))
+
+    def resume(self, job_type: str, job_id: str) -> Ok | Err:
+        return self._with_record(job_type, job_id, lambda r: self._save_result(self.handlers[job_type].resume(r)))
+
+    def promote(self, job_type: str, job_id: str) -> Ok | Err:
+        return self._with_record(
+            job_type, job_id, lambda r: self._save_result(self.handlers[job_type].promote(r, self.config_io))
+        )
+
+    def archive(self, job_type: str, job_id: str) -> Ok | Err:
+        def run(record: dict[str, Any]) -> Ok | Err:
+            result = self.handlers[job_type].archive(record)
+            if result.success:
+                storage.delete_record(job_type, job_id)
+            return result
+
+        return self._with_record(job_type, job_id, run)
+
+    def debug(self, job_type: str, job_id: str) -> Ok | Err:
+        return self._with_record(job_type, job_id, lambda r: self.handlers[job_type].debug(r))
+
+    def capabilities(self, job_type: str) -> dict[str, bool]:
+        return JOB_CAPABILITIES[job_type]
+
+
+def create_job_engine(config_io: ConfigIO | None = None) -> JobEngine:
+    return JobEngine(config_io)

agentcore/operations/jobs/shared/format.py

@@ -0,0 +1,104 @@
+"""Shared presentation helpers for job CLI output (port of operations/jobs/shared/format.ts).
+
+Also hosts the small JavaScript-semantics helpers (``toFixed``, ``parseInt``, ``parseFloat``,
+``toLocaleString``) the eval/jobs commands rely on so output matches the npm CLI.
+"""
+
+import math
+import re
+from datetime import UTC, datetime
+from decimal import ROUND_HALF_UP, Decimal
+from typing import Any
+
+_MONTHS = ("Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec")
+
+
+def to_fixed(value: float, digits: int) -> str:
+    """``Number.prototype.toFixed``: exact-value rounding, ties away from zero."""
+    if value is None or (isinstance(value, float) and math.isnan(value)):
+        return "NaN"
+    if isinstance(value, float) and math.isinf(value):
+        return "Infinity" if value > 0 else "-Infinity"
+    if value == 0:
+        value = 0  # (-0).toFixed() has no sign
+    quantum = Decimal(1).scaleb(-digits)
+    return f"{Decimal(value).quantize(quantum, rounding=ROUND_HALF_UP):f}"
+
+
+def parse_int(value: Any) -> int | None:
+    """``parseInt(value, 10)``: leading integer digits, else NaN (None)."""
+    if value is None:
+        return None
+    m = re.match(r"^\s*([+-]?\d+)", str(value))
+    return int(m.group(1)) if m else None
+
+
+def parse_float(value: Any) -> float | None:
+    """``parseFloat(value)``: leading decimal number, else NaN (None)."""
+    if value is None:
+        return None
+    m = re.match(r"^\s*([+-]?(?:\d+\.?\d*(?:[eE][+-]?\d+)?|\.\d+(?:[eE][+-]?\d+)?|Infinity))", str(value))
+    if not m:
+        return None
+    text = m.group(1)
+    if text.lstrip("+-") == "Infinity":
+        return -math.inf if text.startswith("-") else math.inf
+    return float(text)
+
+
+def parse_js_date(value: Any) -> datetime | None:
+    """``new Date(value)`` for ISO strings and epoch-millisecond numbers. None when invalid."""
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, (int, float)):
+        try:
+            return datetime.fromtimestamp(value / 1000, tz=UTC)
+        except (OverflowError, OSError, ValueError):
+            return None
+    text = str(value).strip()
+    if not text:
+        return None
+    try:
+        parsed = datetime.fromisoformat(text.replace("Z", "+00:00") if text.endswith("Z") else text)
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        # Date-only ISO strings are UTC in JS; date-time strings without offset are local time.
+        parsed = parsed.replace(tzinfo=UTC) if len(text) <= 10 else parsed.astimezone()
+    return parsed
+
+
+def to_locale_string(value: Any) -> str:
+    """``new Date(value).toLocaleString([], {year:'numeric', month:'short', day:'numeric',
+    hour:'2-digit', minute:'2-digit'})`` in the en-US locale, e.g. ``Oct 12, 2026, 03:04 PM``."""
+    parsed = parse_js_date(value)
+    if parsed is None:
+        return "Invalid Date"
+    local = parsed.astimezone()
+    hour12 = local.hour % 12 or 12
+    meridiem = "AM" if local.hour < 12 else "PM"
+    return f"{_MONTHS[local.month - 1]} {local.day}, {local.year}, {hour12:02d}:{local.minute:02d} {meridiem}"
+
+
+def format_job_date(iso: str | None) -> str:
+    """Format an ISO timestamp for CLI tables/detail output (shared by all job types)."""
+    if not iso:
+        return "unknown"
+    return to_locale_string(iso)
+
+
+def iso_now() -> str:
+    """``new Date().toISOString()``."""
+    return to_iso(datetime.now(UTC))
+
+
+def to_iso(dt: datetime) -> str:
+    """``Date.prototype.toISOString`` (UTC, millisecond precision, ``Z`` suffix)."""
+    utc = dt.astimezone(UTC)
+    return utc.strftime("%Y-%m-%dT%H:%M:%S.") + f"{utc.microsecond // 1000:03d}Z"
+
+
+def iso_from_ms(ms: float) -> str:
+    return to_iso(datetime.fromtimestamp(ms / 1000, tz=UTC))

agentcore/operations/jobs/shared/region.py

@@ -0,0 +1,34 @@
+"""Region resolution for jobs (port of operations/jobs/shared/region.ts).
+
+Region is resolved once in create() and baked into the stored ARN; refresh/stop/archive parse it
+back out of the ARN.
+"""
+
+from collections.abc import Sequence
+from typing import Any
+
+from agentcore.aws import region as _region
+from agentcore.aws.arn import region_from_arn
+
+__all__ = ["field", "region_from_arn", "region_of", "resolve_job_region"]
+
+
+def field(obj: Any, key: str, snake: str | None = None) -> Any:
+    """Read ``key`` from a dict or a model attribute (``snake`` name for pydantic models)."""
+    if isinstance(obj, dict):
+        return obj.get(key)
+    return getattr(obj, snake or key, None)
+
+
+def resolve_job_region(opts_region: str | None, aws_targets: Sequence[Any]) -> str:
+    """Explicit option -> first deployment target -> detected region."""
+    if opts_region:
+        return opts_region
+    if aws_targets and field(aws_targets[0], "region"):
+        return str(field(aws_targets[0], "region"))
+    return _region.detect_region().region
+
+
+def region_of(arn: str) -> str:
+    """Region parsed from a stored ARN, else the detected region."""
+    return region_from_arn(arn) or _region.detect_region().region

agentcore/operations/jobs/shared/resolve_agent_state.py

@@ -0,0 +1,30 @@
+"""Resolve a deployed agent runtime by name (port of operations/jobs/shared/resolve-agent-state.ts).
+
+``deployed_state`` is the camelCase dict form of ``deployed-state.json``.
+"""
+
+from typing import Any
+
+from agentcore.lib.schemas.io.config_io import to_jsonable
+
+
+def deployed_dict(deployed_state: Any) -> dict[str, Any]:
+    """camelCase dict view of a DeployedState model (or pass a dict through)."""
+    data = to_jsonable(deployed_state) if not isinstance(deployed_state, dict) else deployed_state
+    return data if isinstance(data, dict) else {"targets": {}}
+
+
+def iter_target_resources(deployed_state: dict[str, Any]):
+    for target in (deployed_state.get("targets") or {}).values():
+        resources = (target or {}).get("resources")
+        if resources:
+            yield resources
+
+
+def resolve_agent_state(deployed_state: dict[str, Any], agent_name: str) -> dict[str, Any] | None:
+    """The agent runtime across all deployment targets; None if not deployed."""
+    for resources in iter_target_resources(deployed_state):
+        agent = (resources.get("runtimes") or {}).get(agent_name)
+        if agent is not None:
+            return agent
+    return None

agentcore/operations/jobs/shared/storage.py

@@ -0,0 +1,117 @@
+"""Pure file I/O for job records (port of operations/jobs/shared/storage.ts).
+
+Layout: ``<configRoot>/.cli/jobs/{STORAGE_DIRS[type]}/{id}.json``, written as
+``JSON.stringify(record, null, 2)`` so the npm CLI and this port read each other's files.
+
+- atomic writes (temp file + rename),
+- per-file parse guard in ``list_records`` (a corrupt file is skipped),
+- ``assert_safe_id`` path-traversal guard; the content ``id`` is authoritative over the filename.
+"""
+
+import json
+import os
+import re
+from typing import Any
+
+from agentcore.lib import CLI_SYSTEM_DIR, NoProjectError, find_config_root
+from agentcore.lib.utils.json_format import to_json_string
+from agentcore.operations.jobs.shared.constants import STORAGE_DIRS
+
+
+def _cli_dir() -> str:
+    config_root = find_config_root()
+    if not config_root:
+        raise NoProjectError()
+    return os.path.join(config_root, CLI_SYSTEM_DIR)
+
+
+def dir_for(job_type: str) -> str:
+    return os.path.join(_cli_dir(), "jobs", STORAGE_DIRS[job_type])
+
+
+def _file_for(job_type: str, job_id: str) -> str:
+    return os.path.join(dir_for(job_type), f"{job_id}.json")
+
+
+def assert_safe_id(job_id: str) -> None:
+    """Reject ids that could escape the storage directory."""
+    if not job_id or re.search(r"[/\\]", job_id):
+        raise ValueError("Invalid job id: must be non-empty and contain no path separators")
+
+
+def _is_job_record_of_type(value: Any, job_type: str) -> bool:
+    if not isinstance(value, dict):
+        return False
+    job_id = value.get("id")
+    return value.get("type") == job_type and isinstance(job_id, str) and len(job_id) > 0
+
+
+def drop_undefined(value: Any) -> Any:
+    """Recursively drop ``None`` dict values (JS ``undefined`` is omitted by JSON.stringify)."""
+    if isinstance(value, dict):
+        return {k: drop_undefined(v) for k, v in value.items() if v is not None}
+    if isinstance(value, list):
+        return [drop_undefined(v) for v in value]
+    return value
+
+
+def record_json(record: dict[str, Any], indent: int | None = 2) -> str:
+    return to_json_string(drop_undefined(record), indent)
+
+
+def save_record(record: dict[str, Any]) -> str:
+    """Persist a record atomically (temp file + rename). Returns the file path."""
+    assert_safe_id(record["id"])
+    directory = dir_for(record["type"])
+    os.makedirs(directory, exist_ok=True)
+    file_path = _file_for(record["type"], record["id"])
+    tmp_path = f"{file_path}.tmp"
+    with open(tmp_path, "w", encoding="utf-8", newline="") as fh:
+        fh.write(record_json(record))
+    os.replace(tmp_path, file_path)
+    return file_path
+
+
+def load_record(job_type: str, job_id: str) -> dict[str, Any] | None:
+    """One record, or None if missing, unparseable, or a legacy/foreign shape."""
+    assert_safe_id(job_id)
+    file_path = _file_for(job_type, job_id)
+    if not os.path.exists(file_path):
+        return None
+    try:
+        with open(file_path, encoding="utf-8") as fh:
+            parsed = json.load(fh)
+    except (OSError, ValueError):
+        return None
+    return parsed if _is_job_record_of_type(parsed, job_type) else None
+
+
+def list_records(job_type: str | None = None) -> list[dict[str, Any]]:
+    """Records for one type (or all types). Skips corrupt/legacy files; never raises on a bad file."""
+    types = [job_type] if job_type else list(STORAGE_DIRS)
+    records: list[dict[str, Any]] = []
+    for t in types:
+        directory = dir_for(t)
+        if not os.path.isdir(directory):
+            continue
+        for name in os.listdir(directory):
+            if not name.endswith(".json"):
+                continue
+            try:
+                with open(os.path.join(directory, name), encoding="utf-8") as fh:
+                    parsed = json.load(fh)
+            except (OSError, ValueError):
+                continue
+            if _is_job_record_of_type(parsed, t):
+                records.append(parsed)
+    return records
+
+
+def delete_record(job_type: str, job_id: str) -> bool:
+    """Delete the local record file. True if it existed and was removed."""
+    assert_safe_id(job_id)
+    file_path = _file_for(job_type, job_id)
+    if not os.path.exists(file_path):
+        return False
+    os.remove(file_path)
+    return True

agentcore/operations/jobs/shared/wait.py

@@ -0,0 +1,30 @@
+"""Block until a job reaches a terminal state (port of operations/jobs/shared/wait.ts)."""
+
+import time
+from collections.abc import Callable
+from typing import Any
+
+from agentcore.operations.jobs.shared.constants import is_terminal
+
+DEFAULT_POLL_INTERVAL_MS = 5000
+
+
+def wait_for_terminal(
+    engine: Any,
+    job_type: str,
+    job_id: str,
+    *,
+    poll_interval_ms: int = DEFAULT_POLL_INTERVAL_MS,
+    on_tick: Callable[[str], None] | None = None,
+    sleep: Callable[[float], None] = time.sleep,
+) -> dict[str, Any] | None:
+    """Poll ``engine.get`` until terminal; None if the job vanished from local storage."""
+    while True:
+        record = engine.get(job_type, job_id)
+        if record is None:
+            return None
+        if on_tick:
+            on_tick(record["status"])
+        if is_terminal(record):
+            return record
+        sleep(poll_interval_ms / 1000)

agentcore/operations/knowledge_base/__init__.py

@@ -0,0 +1,33 @@
+"""Knowledge base operations (port of upstream ``src/cli/operations/knowledge-base``)."""
+
+from agentcore.operations.knowledge_base.connector_config import (
+    CONNECTOR_TYPE_BY_FLAG,
+    DATA_SOURCE_TYPE_FLAGS,
+    FLAG_BY_CONNECTOR_TYPE,
+    ConnectorConfigReadResult,
+    DataSourceTypeFlag,
+    DataSourceWireType,
+    extract_secret_arn,
+    flag_to_wire_type,
+    is_connector_config_type,
+    read_connector_config,
+)
+from agentcore.operations.knowledge_base.hydrate_data_sources import (
+    hydrate_knowledge_base_data_sources,
+    uri_hash_prefix,
+)
+
+__all__ = [
+    "CONNECTOR_TYPE_BY_FLAG",
+    "DATA_SOURCE_TYPE_FLAGS",
+    "FLAG_BY_CONNECTOR_TYPE",
+    "ConnectorConfigReadResult",
+    "DataSourceTypeFlag",
+    "DataSourceWireType",
+    "extract_secret_arn",
+    "flag_to_wire_type",
+    "hydrate_knowledge_base_data_sources",
+    "is_connector_config_type",
+    "read_connector_config",
+    "uri_hash_prefix",
+]

agentcore/operations/knowledge_base/connector_config.py

@@ -0,0 +1,105 @@
+"""Connector-config flag mapping and file validation (port of operations/knowledge-base/connector-config.ts)."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from typing import Any, Final, Literal
+
+DataSourceTypeFlag = Literal["s3", "web-crawler", "confluence", "sharepoint", "onedrive", "google-drive"]
+DataSourceWireType = Literal["S3", "WEB", "CONFLUENCE", "SHAREPOINT", "ONEDRIVE", "GOOGLEDRIVE"]
+
+# User-facing `--data-source-type` flag values, including S3 (the default).
+DATA_SOURCE_TYPE_FLAGS: Final[tuple[str, ...]] = (
+    "s3",
+    "web-crawler",
+    "confluence",
+    "sharepoint",
+    "onedrive",
+    "google-drive",
+)
+
+# The single translation table: user flag -> wire `type`.
+CONNECTOR_TYPE_BY_FLAG: Final[dict[str, str]] = {
+    "s3": "S3",
+    "web-crawler": "WEB",
+    "confluence": "CONFLUENCE",
+    "sharepoint": "SHAREPOINT",
+    "onedrive": "ONEDRIVE",
+    "google-drive": "GOOGLEDRIVE",
+}
+
+# Inverse table, for rendering a wire type back as a user-facing flag.
+FLAG_BY_CONNECTOR_TYPE: Final[dict[str, str]] = {wire: flag for flag, wire in CONNECTOR_TYPE_BY_FLAG.items()}
+
+# Connector wire types that require a secretArn unless explicitly NO_AUTH.
+_SECRET_BEARING: Final = frozenset({"CONFLUENCE", "SHAREPOINT", "ONEDRIVE", "GOOGLEDRIVE"})
+
+
+def flag_to_wire_type(flag: str) -> str:
+    wire = CONNECTOR_TYPE_BY_FLAG.get(flag)
+    if not wire:
+        raise ValueError(f'Unknown data source type "{flag}". Expected one of: {", ".join(DATA_SOURCE_TYPE_FLAGS)}.')
+    return wire
+
+
+def is_connector_config_type(wire: str) -> bool:
+    """True for every wire type that uses a connectorConfigFile (i.e. not S3)."""
+    return wire != "S3" and wire in FLAG_BY_CONNECTOR_TYPE
+
+
+@dataclass
+class ConnectorConfigReadResult:
+    parsed: dict[str, Any]
+    """The parsed connectorParameters object, passed through to the L3 verbatim."""
+    warnings: list[str] = field(default_factory=list)
+    """Non-fatal advisories surfaced to the user (e.g. missing secretArn)."""
+
+
+def read_connector_config(path: str, declared_type: str) -> ConnectorConfigReadResult:
+    """Read a ``--connector-config`` JSON file and validate it lightly.
+
+    Only checks: the file exists, parses, carries a ``type`` matching the declared connector type,
+    and (for auth connectors) warns when no secretArn is present.
+    """
+    resolved = os.path.abspath(path)
+    if not os.path.exists(resolved):
+        raise ValueError(f"Connector config file not found: {path}")
+    try:
+        with open(resolved, encoding="utf-8") as fh:
+            parsed = json.load(fh)
+    except (ValueError, UnicodeDecodeError):
+        raise ValueError(f"Connector config file is not valid JSON: {path}") from None
+    if not parsed or not isinstance(parsed, dict):
+        raise ValueError(f"Connector config file must be a JSON object: {path}")
+    if not isinstance(parsed.get("type"), str):
+        raise ValueError(f'Connector config file is missing a "type" field: {path}')
+    if parsed["type"] != declared_type:
+        raise ValueError(
+            f'Connector config "type" ({parsed["type"]}) does not match the declared data source type '
+            f"({declared_type}) in {path}."
+        )
+
+    warnings: list[str] = []
+    cc = parsed.get("connectionConfiguration")
+    cc = cc if isinstance(cc, dict) else None
+    has_secret = cc is not None and isinstance(cc.get("secretArn"), str) and bool(cc.get("secretArn"))
+    if declared_type in _SECRET_BEARING and not has_secret:
+        warnings.append(
+            f"Connector config {path} has no connectionConfiguration.secretArn; {declared_type} ingestion will "
+            "fail at deploy until credentials are provided."
+        )
+    if declared_type == "WEB":
+        auth_type = cc.get("authType") if cc is not None and isinstance(cc.get("authType"), str) else None
+        if auth_type and auth_type != "NO_AUTH" and not has_secret:
+            warnings.append(f"Connector config {path} uses authType {auth_type} but has no secretArn.")
+
+    return ConnectorConfigReadResult(parsed=parsed, warnings=warnings)
+
+
+def extract_secret_arn(parsed: dict[str, Any]) -> str | None:
+    """Pull connectionConfiguration.secretArn from a parsed connector config, if present."""
+    cc = parsed.get("connectionConfiguration")
+    arn = cc.get("secretArn") if isinstance(cc, dict) else None
+    return arn if isinstance(arn, str) and arn else None