agentcore-cli 0.31.1__py3-none-any.whl

agentcore/operations/jobs/recommendation/fetch_session_spans.py

@@ -0,0 +1,93 @@
+"""Fetch OTEL span + log records for one session (port of recommendation/fetch-session-spans.ts).
+
+Tool description recommendations need inline ``sessionSpans``: span records from ``aws/spans`` plus
+log records (body.input/output.messages) from the runtime log group.
+"""
+
+import json
+import time
+from collections.abc import Callable
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any
+
+from agentcore.aws import cloudwatch
+from agentcore.aws._aws_errors import aws_error_name
+
+SPANS_LOG_GROUP = "aws/spans"
+
+
+def _collect_log_events(**options: Any) -> list[dict[str, Any]]:
+    try:
+        return list(cloudwatch.search_logs(**options))
+    except Exception as exc:
+        message = str(exc)
+        if (
+            aws_error_name(exc) == "ResourceNotFoundException"
+            or "ResourceNotFoundException" in message
+            or "does not exist" in message
+        ):
+            return []
+        raise
+
+
+def _matches_session(record: dict[str, Any], session_id: str) -> bool:
+    attrs = record.get("attributes")
+    if isinstance(attrs, dict) and attrs.get("session.id") == session_id:
+        return True
+    body = record.get("body")
+    if body:
+        return session_id in json.dumps(body, separators=(",", ":"), ensure_ascii=False)
+    return False
+
+
+def fetch_session_spans(
+    *,
+    region: str,
+    runtime_id: str,
+    session_id: str,
+    lookback_days: int = 7,
+    on_progress: Callable[[str], None] | None = None,
+) -> dict[str, Any]:
+    """{"spans": [...], "spanRecordCount": n, "logRecordCount": m}"""
+    progress = on_progress or (lambda _m: None)
+    runtime_group = cloudwatch.runtime_log_group(runtime_id)
+    end_ms = int(time.time() * 1000)
+    start_ms = end_ms - lookback_days * 24 * 60 * 60 * 1000
+    session_filter = f'"session.id" "{session_id}"'
+    common = {"region": region, "start_time_ms": start_ms, "end_time_ms": end_ms}
+
+    progress("Fetching span records from aws/spans and runtime log group...")
+    with ThreadPoolExecutor(max_workers=3) as pool:
+        shared_f = pool.submit(
+            _collect_log_events, log_group_name=SPANS_LOG_GROUP, filter_pattern=session_filter, **common
+        )
+        runtime_f = pool.submit(
+            _collect_log_events, log_group_name=runtime_group, filter_pattern=session_filter, **common
+        )
+        logs_f = pool.submit(
+            _collect_log_events, log_group_name=runtime_group, filter_pattern='"body" "input"', **common
+        )
+        span_records = shared_f.result() + runtime_f.result()
+        log_records = logs_f.result()
+
+    progress(f"Found {len(span_records)} span records, {len(log_records)} log record candidates")
+
+    spans: list[Any] = []
+    for event in span_records:
+        try:
+            spans.append(json.loads(event["message"]))
+        except ValueError:
+            continue
+
+    log_count = 0
+    for event in log_records:
+        try:
+            parsed = json.loads(event["message"])
+        except ValueError:
+            continue
+        if isinstance(parsed, dict) and _matches_session(parsed, session_id):
+            spans.append(parsed)
+            log_count += 1
+
+    progress(f"Combined {len(spans)} spans ({len(spans) - log_count} span records + {log_count} log records)")
+    return {"spans": spans, "spanRecordCount": len(spans) - log_count, "logRecordCount": log_count}

agentcore/operations/jobs/recommendation/format.py

@@ -0,0 +1,77 @@
+"""Presentation helpers for recommendation jobs (port of operations/jobs/recommendation/format.ts)."""
+
+from typing import Any
+
+import typer
+
+from agentcore.operations.jobs.shared.format import format_job_date
+
+
+def short_type(rec_type: str | None) -> str:
+    if rec_type == "SYSTEM_PROMPT_RECOMMENDATION":
+        return "System Prompt"
+    if rec_type == "TOOL_DESCRIPTION_RECOMMENDATION":
+        return "Tool Description"
+    return str(rec_type)
+
+
+def print_recommendation_history(records: list[dict[str, Any]]) -> None:
+    if not records:
+        typer.echo("No recommendation jobs found. Run `agentcore run recommendation` to create one.")
+        return
+    typer.echo(f"\n{'Date'.ljust(22)} {'Status'.ljust(14)} {'Type'.ljust(18)} {'Agent'.ljust(18)} ID")
+    typer.echo("─" * 100)
+    for r in records:
+        agent = r.get("agent")
+        typer.echo(
+            f"{format_job_date(r.get('createdAt')).ljust(22)} {str(r.get('status')).ljust(14)} "
+            f"{short_type(r.get('recommendationType')).ljust(18)} "
+            f"{(agent if agent is not None else 'unknown').ljust(18)} {r['id']}"
+        )
+    typer.echo("")
+
+
+def failure_text(record: dict[str, Any]) -> str:
+    if record.get("failureDetail") is not None:
+        return record["failureDetail"]
+    if record.get("statusReasons") is not None:
+        return "; ".join(record["statusReasons"])
+    return "unknown"
+
+
+def print_recommendation_detail(record: dict[str, Any]) -> None:
+    typer.echo(f"\nRecommendation: {record['id']}")
+    typer.echo(f"Status: {record.get('status')}")
+    typer.echo(f"Agent: {record.get('agent')}")
+    typer.echo(f"Type: {short_type(record.get('recommendationType'))}")
+    typer.echo(f"Evaluators: {', '.join(record.get('evaluators') or []) or '(none)'}")
+    typer.echo(f"Started: {format_job_date(record.get('createdAt'))}")
+    if record.get("completedAt"):
+        typer.echo(f"Completed: {format_job_date(record['completedAt'])}")
+    if record.get("kmsKeyArn"):
+        typer.echo(f"KMS Key: {record['kmsKeyArn']}")
+
+    result = record.get("result") or {}
+    sys_result = result.get("systemPromptRecommendationResult") or {}
+    tool_result = result.get("toolDescriptionRecommendationResult") or {}
+    if sys_result.get("recommendedSystemPrompt"):
+        typer.echo("\n+++ Recommended System Prompt +++")
+        typer.echo(sys_result["recommendedSystemPrompt"])
+        if sys_result.get("explanation"):
+            typer.echo("\n--- Explanation ---")
+            typer.echo(sys_result["explanation"])
+    elif tool_result.get("tools"):
+        for t in tool_result["tools"]:
+            typer.echo(f"\nTool: {t.get('toolName')}")
+            typer.echo(f"Recommended: {t.get('recommendedToolDescription')}")
+            if t.get("explanation"):
+                typer.echo(f"Explanation: {t['explanation']}")
+    elif record.get("status") == "FAILED":
+        typer.echo(f"\nError: {failure_text(record)}")
+    else:
+        typer.echo("\nResult not yet available.")
+    if record.get("syncedVersionId"):
+        typer.echo(f"\nNew config bundle version {record['syncedVersionId']} applied to agentcore.json.")
+    if record.get("logFilePath"):
+        typer.echo(f"\nLog: {record['logFilePath']}")
+    typer.echo("")

agentcore/operations/jobs/recommendation/handler.py

@@ -0,0 +1,331 @@
+"""Recommendation job handler (port of operations/jobs/recommendation/handler.ts).
+
+- create():  resolve agent + evaluator(s), build the recommendationConfig, ONE StartRecommendation.
+- refresh(): GET latest status (404 -> NOT_FOUND); copy result / failure detail.
+- settle():  once COMPLETED for a config-bundle input, sync the new bundle version into
+             agentcore.json exactly once (``syncedVersionId``).
+- archive(): DeleteRecommendation (recommendations have no Stop).
+"""
+
+import re
+import time
+from typing import Any
+
+from agentcore.aws import agentcore_recommendation as api
+from agentcore.lib import ConfigIO, JobNotFoundError, ResourceNotFoundError, ValidationError
+from agentcore.lib.errors.types import to_error
+from agentcore.lib.result import Err, Ok
+from agentcore.lib.schemas.io.config_io import to_jsonable
+from agentcore.lib.utils.json_format import to_json_string
+from agentcore.operations.jobs.batch_evaluation.handler import new_logger
+from agentcore.operations.jobs.recommendation import apply_to_bundle as _apply
+from agentcore.operations.jobs.recommendation import build_config as _build
+from agentcore.operations.jobs.shared.constants import (
+    MAX_INLINE_TEXT_LENGTH,
+    NOT_FOUND_STATUS,
+    RECOMMENDATION_NAME_REGEX,
+    TERMINAL_STATUSES,
+)
+from agentcore.operations.jobs.shared.format import iso_now
+from agentcore.operations.jobs.shared.region import region_of, resolve_job_region
+from agentcore.operations.jobs.shared.resolve_agent_state import deployed_dict, resolve_agent_state
+from agentcore.operations.jobs.shared.storage import drop_undefined
+
+MAX_RECOMMENDATION_NAME_LENGTH = 48
+
+
+def auto_recommendation_name(project_name: str, agent: str | None, now: int | None = None) -> str:
+    """``<project>_<agent>_<timestamp>`` sanitized/truncated to satisfy RECOMMENDATION_NAME_REGEX."""
+    suffix = str(now if now is not None else int(time.time() * 1000))
+    max_prefix = MAX_RECOMMENDATION_NAME_LENGTH - len(suffix) - 1
+    raw = f"{project_name}_{agent}" if agent else project_name
+    prefix = re.sub(r"[^a-zA-Z0-9_-]", "_", raw)[: max(1, max_prefix)]
+    if not re.match(r"^[a-zA-Z]", prefix):
+        prefix = f"r{prefix}"[: max(1, max_prefix)]
+    return f"{prefix}_{suffix}"
+
+
+def _fail(logger: Any, err: BaseException, end_step: bool = True) -> Err:
+    if logger:
+        if end_step:
+            logger.end_step("error", str(err))
+        logger.finalize(False)
+    return Err(err)
+
+
+def create(opts: dict[str, Any], config_io: ConfigIO) -> Ok | Err:
+    logger = new_logger("recommend")
+    try:
+        if logger:
+            logger.start_step("Load project config")
+        project = to_jsonable(config_io.read_project_spec())
+        deployed_state = deployed_dict(config_io.read_deployed_state())
+        aws_targets = config_io.resolve_aws_deployment_targets()
+        region = resolve_job_region(opts.get("region"), aws_targets)
+        if logger:
+            logger.log(f"Region: {region}")
+            logger.end_step("success")
+            logger.start_step("Resolve agent and evaluators")
+
+        agent = opts.get("agent")
+        trace_source = opts["traceSource"]
+        agent_state = resolve_agent_state(deployed_state, agent) if agent else None
+        source_needs_no_agent = trace_source in ("batch-evaluation", "online-evaluation")
+        if not agent_state and not source_needs_no_agent:
+            return _fail(logger, ResourceNotFoundError(f'Agent "{agent}" not deployed. Run `agentcore deploy` first.'))
+
+        evaluator_ids: list[str] = []
+        for evaluator in opts.get("evaluators") or []:
+            resolved = _build.resolve_evaluator_id(deployed_state, evaluator, region)
+            if not resolved:
+                return _fail(
+                    logger,
+                    ResourceNotFoundError(
+                        f'Evaluator "{evaluator}" not found. Use a Builtin.* name, a full ARN, or deploy a custom '
+                        "evaluator first."
+                    ),
+                )
+            evaluator_ids.append(resolved)
+        rec_type = opts["type"]
+        if rec_type == "SYSTEM_PROMPT_RECOMMENDATION":
+            too_few = not source_needs_no_agent and len(evaluator_ids) != 1
+            too_many = len(evaluator_ids) > 1
+            if too_few or too_many:
+                return _fail(
+                    logger,
+                    ValidationError(
+                        "System prompt recommendations accept at most one evaluator."
+                        if too_many
+                        else "System prompt recommendations require exactly one evaluator."
+                    ),
+                )
+        if logger:
+            logger.log(f"Evaluators: {', '.join(evaluator_ids) or '(none)'}")
+            logger.end_step("success")
+
+        input_source = opts["inputSource"]
+        inline_content: str | None = None
+        if input_source == "file" and opts.get("promptFile"):
+            with open(opts["promptFile"], encoding="utf-8") as fh:
+                inline_content = fh.read()
+        elif input_source == "inline":
+            inline_content = opts.get("inlineContent")
+        if (
+            rec_type == "SYSTEM_PROMPT_RECOMMENDATION"
+            and input_source != "config-bundle"
+            and not (inline_content or "").strip()
+        ):
+            return _fail(
+                logger,
+                ValidationError(
+                    "System prompt content is required. Provide via --inline, --prompt-file, or --bundle-name."
+                ),
+                end_step=False,
+            )
+        if inline_content and len(inline_content) > MAX_INLINE_TEXT_LENGTH:
+            return _fail(
+                logger,
+                ValidationError(
+                    f"Inline text exceeds the maximum allowed length ({len(inline_content)} characters, limit is "
+                    f"{MAX_INLINE_TEXT_LENGTH})."
+                ),
+                end_step=False,
+            )
+
+        account_id = _build.extract_account_id_from_arn(agent_state["runtimeArn"]) if agent_state else ""
+
+        bundle_name = opts.get("bundleName")
+        bundle_arn: str | None = None
+        bundle_version = opts.get("bundleVersion")
+        prompt_path = opts.get("systemPromptJsonPath")
+        if input_source == "config-bundle" and bundle_name:
+            if bundle_name.startswith("arn:"):
+                bundle_arn = bundle_name
+            else:
+                for target in (deployed_state.get("targets") or {}).values():
+                    bundle = ((((target or {}).get("resources")) or {}).get("configBundles") or {}).get(bundle_name)
+                    if bundle and bundle.get("bundleArn"):
+                        bundle_arn = bundle["bundleArn"]
+                        break
+                if not bundle_arn:
+                    return _fail(
+                        logger,
+                        ResourceNotFoundError(
+                            f'Config bundle "{bundle_name}" not found in deployed state. Run `agentcore deploy` first.'
+                        ),
+                        end_step=False,
+                    )
+            if bundle_version == "LATEST" and bundle_arn:
+                version_id = _build.resolve_bundle_version_id(bundle_arn, bundle_version, deployed_state)
+                if not version_id:
+                    return _fail(
+                        logger,
+                        ResourceNotFoundError(
+                            f'Could not resolve version "LATEST" for config bundle "{bundle_name}". '
+                            "Run `agentcore deploy` first, or pass an explicit version UUID."
+                        ),
+                        end_step=False,
+                    )
+                bundle_version = version_id
+            if prompt_path and not prompt_path.startswith("$"):
+                local_name = bundle_name
+                if bundle_name.startswith("arn:"):
+                    local_name = next(
+                        (
+                            n
+                            for t in (deployed_state.get("targets") or {}).values()
+                            for n, b in ((((t or {}).get("resources")) or {}).get("configBundles") or {}).items()
+                            if b.get("bundleArn") == bundle_name
+                        ),
+                        None,
+                    )
+                if local_name:
+                    proj_bundle = next(
+                        (b for b in project.get("configBundles") or [] if b.get("name") == local_name), None
+                    )
+                    components = (proj_bundle or {}).get("components")
+                    if components:
+                        first_key = next(iter(components), None)
+                        if first_key:
+                            resolved_key = _build.resolve_component_key_for_json_path(first_key, deployed_state)
+                            prompt_path = f"$.{resolved_key}.configuration.{prompt_path}"
+
+        config = _build.build_recommendation_config(
+            type=rec_type,
+            inline_content=inline_content,
+            bundle_arn=bundle_arn,
+            bundle_version=bundle_version,
+            system_prompt_json_path=prompt_path,
+            tool_desc_json_paths=opts.get("toolDescJsonPaths"),
+            input_source=input_source,
+            tools=opts.get("tools"),
+            trace_source=trace_source,
+            lookback_days=opts.get("lookbackDays"),
+            session_ids=opts.get("sessionIds"),
+            spans_file=opts.get("spansFile"),
+            from_insights=opts.get("fromInsights"),
+            batch_evaluation_arn=opts.get("batchEvaluationArn"),
+            online_evaluation_arn=opts.get("onlineEvaluationArn"),
+            runtime_id=(agent_state or {}).get("runtimeId", ""),
+            account_id=account_id,
+            region=region,
+            evaluator_ids=evaluator_ids,
+            on_progress=opts.get("onProgress"),
+            logger=logger,
+        )
+
+        if logger:
+            logger.start_step("Start recommendation")
+        explicit_name = opts.get("recommendationName")
+        name = explicit_name if explicit_name is not None else auto_recommendation_name(project["name"], agent)
+        if explicit_name and not RECOMMENDATION_NAME_REGEX.match(explicit_name):
+            return _fail(
+                logger,
+                ValidationError(
+                    f'Recommendation name "{explicit_name}" is invalid. Must begin with a letter and contain only '
+                    "alphanumeric characters, underscores, or hyphens (max 48 chars)."
+                ),
+            )
+        on_progress = opts.get("onProgress")
+        if on_progress:
+            on_progress("starting", f'Starting recommendation "{name}"...')
+        start = api.start_recommendation(
+            region=region,
+            name=name,
+            type=rec_type,
+            recommendation_config=config,
+            kms_key_arn=opts.get("kmsKeyArn") or None,
+        )
+        if logger:
+            logger.log(f"Response: {to_json_string(start)}")
+            logger.end_step("success")
+        if on_progress:
+            on_progress("started", f"Recommendation created: {start['recommendationId']} ({start['status']})")
+        if logger:
+            logger.finalize(True)
+
+        record: dict[str, Any] = {
+            "type": "recommendation",
+            "id": start["recommendationId"],
+            "arn": start["recommendationArn"],
+            "status": start["status"],
+            "createdAt": start.get("createdAt") or iso_now(),
+            "agent": agent or "",
+            "logFilePath": logger.log_file_path if logger else None,
+            "recommendationType": rec_type,
+            "evaluators": opts.get("evaluators") or [],
+            "inputSource": input_source,
+            "bundleName": bundle_name,
+            "bundleArn": bundle_arn,
+            "bundleVersion": bundle_version,
+            "systemPromptJsonPath": prompt_path,
+            "toolDescJsonPaths": opts.get("toolDescJsonPaths"),
+        }
+        if opts.get("kmsKeyArn"):
+            record["kmsKeyArn"] = opts["kmsKeyArn"]
+        return Ok(drop_undefined(record))
+    except Exception as exc:  # noqa: BLE001
+        if logger:
+            logger.finalize(False)
+        return Err(to_error(exc))
+
+
+def refresh(record: dict[str, Any]) -> Ok | Err:
+    region = region_of(record["arn"])
+    try:
+        response = api.get_recommendation(region=region, recommendation_id=record["id"])
+    except JobNotFoundError:
+        return Ok({**record, "status": NOT_FOUND_STATUS})
+    except Exception as exc:  # noqa: BLE001
+        return Err(to_error(exc))
+
+    status = response["status"]
+    failure = (
+        _build.extract_failure_details(response.get("statusReasons"), response.get("recommendationResult"))
+        if status == "FAILED"
+        else None
+    )
+    terminal = status in TERMINAL_STATUSES["recommendation"]
+    completed_at = (
+        (response.get("completedAt") or response.get("updatedAt") or record.get("completedAt")) if terminal else None
+    )
+    updated = {
+        **record,
+        "status": status,
+        "completedAt": completed_at,
+        "result": response.get("recommendationResult") or record.get("result"),
+        "statusReasons": response.get("statusReasons") or record.get("statusReasons"),
+        "failureDetail": failure or record.get("failureDetail"),
+    }
+    return Ok(drop_undefined(updated))
+
+
+def settle(record: dict[str, Any], config_io: ConfigIO) -> dict[str, Any]:
+    if record.get("inputSource") != "config-bundle" or record.get("status") != "COMPLETED" or not record.get("result"):
+        return record
+    result = record["result"]
+    result_bundle = (result.get("systemPromptRecommendationResult") or {}).get("configurationBundle") or (
+        result.get("toolDescriptionRecommendationResult") or {}
+    ).get("configurationBundle")
+    if not result_bundle or record.get("syncedVersionId") == result_bundle.get("versionId"):
+        return record
+    applied = _apply.apply_recommendation_to_bundle(
+        bundle_name=record.get("bundleName"),
+        bundle_arn=record.get("bundleArn"),
+        result=result,
+        region=region_of(record["arn"]),
+        config_io=config_io,
+    )
+    if applied.success:
+        return {**record, "syncedVersionId": result_bundle["versionId"]}
+    return record
+
+
+def archive(record: dict[str, Any]) -> Ok | Err:
+    try:
+        api.delete_recommendation(region=region_of(record["arn"]), recommendation_id=record["id"])
+        return Ok(None)
+    except JobNotFoundError:
+        return Ok(None)
+    except Exception as exc:  # noqa: BLE001
+        return Err(to_error(exc))

agentcore/operations/jobs/shared/constants.py

@@ -0,0 +1,85 @@
+"""Job Engine constants (port of operations/jobs/shared/constants.ts).
+
+Storage directory names, per-type terminal-status sets, capability flags and shared validation
+patterns. Job records are plain camelCase dicts (the on-disk JSON shape shared with the npm CLI).
+"""
+
+import re
+from typing import Any, Final
+
+JOB_TYPES: Final = ("recommendation", "batch-evaluation", "ab-test", "insights")
+
+# Local storage directory per job type, under `<configRoot>/.cli/jobs/`.
+STORAGE_DIRS: Final[dict[str, str]] = {
+    "recommendation": "recommendations",
+    "batch-evaluation": "batch-eval-results",
+    "ab-test": "ab-tests",
+    "insights": "insights",
+}
+
+# Human-readable label per job type, for user-facing messages (e.g. "not found" errors).
+JOB_TYPE_LABELS: Final[dict[str, str]] = {
+    "recommendation": "Recommendation",
+    "batch-evaluation": "Batch evaluation",
+    "ab-test": "A/B test",
+    "insights": "Insights job",
+}
+
+# Sentinel status set when a refresh GET 404s (job deleted on the service). Terminal for all types.
+NOT_FOUND_STATUS: Final = "NOT_FOUND"
+
+TERMINAL_STATUSES: Final[dict[str, frozenset[str]]] = {
+    "recommendation": frozenset({"COMPLETED", "FAILED", "SUCCEEDED", "DELETING", NOT_FOUND_STATUS}),
+    "batch-evaluation": frozenset(
+        {"COMPLETED", "COMPLETED_WITH_ERRORS", "FAILED", "STOPPED", "CANCELLED", NOT_FOUND_STATUS}
+    ),
+    # AB test: `status` holds lifecycle status (ACTIVE/FAILED/CREATE_FAILED).
+    "ab-test": frozenset({"FAILED", "CREATE_FAILED", "UPDATE_FAILED", "DELETE_FAILED", NOT_FOUND_STATUS}),
+    "insights": frozenset({"COMPLETED", "COMPLETED_WITH_ERRORS", "FAILED", "STOPPED", NOT_FOUND_STATUS}),
+}
+
+# Runtime capability flags (TUI display only).
+JOB_CAPABILITIES: Final[dict[str, dict[str, bool]]] = {
+    "recommendation": {"canStop": False, "canPause": False, "canPromote": False, "canDebug": False},
+    "batch-evaluation": {"canStop": True, "canPause": False, "canPromote": False, "canDebug": False},
+    "ab-test": {"canStop": True, "canPause": True, "canPromote": True, "canDebug": True},
+    "insights": {"canStop": False, "canPause": False, "canPromote": False, "canDebug": False},
+}
+
+STOPPABLE_JOB_TYPES: Final = ("batch-evaluation", "ab-test")
+PAUSABLE_JOB_TYPES: Final = ("ab-test",)
+PROMOTABLE_JOB_TYPES: Final = ("ab-test",)
+DEBUGGABLE_JOB_TYPES: Final = ("ab-test",)
+
+# Maximum character length for inline text input (system prompt or tool descriptions).
+MAX_INLINE_TEXT_LENGTH: Final = 20_000
+
+# Recommendation name rule: start with a letter, alphanumeric + underscore/hyphen, max 48 chars.
+RECOMMENDATION_NAME_REGEX: Final = re.compile(r"^[a-zA-Z][a-zA-Z0-9_-]{0,47}$")
+
+# Maximum number of inline spans the API accepts.
+MAX_INLINE_SPANS: Final = 1000
+
+# Recommendation tool name rule: alphanumeric + underscore/hyphen/dot, max 256 chars.
+TOOL_NAME_REGEX: Final = re.compile(r"^[a-zA-Z0-9_\-.]+$")
+MAX_TOOL_NAME_LENGTH: Final = 256
+
+# Batch-evaluation name rule: start with a letter, then letters/digits/underscores, max 48 chars.
+BATCH_EVAL_NAME_REGEX: Final = re.compile(r"^[a-zA-Z][a-zA-Z0-9_]{0,47}$")
+
+
+def is_terminal(record: dict[str, Any]) -> bool:
+    """Whether a record is in a terminal state AND fully settled (no further work on read).
+
+    A terminal batch-evaluation whose per-session results have not yet been fetched is kept
+    refreshable; so is a terminal AB test whose failureReason was not captured yet.
+    """
+    if record.get("error"):
+        return True  # refresh retries exhausted — settled with an error
+    job_type = record.get("type")
+    status = record.get("status")
+    if status not in TERMINAL_STATUSES.get(job_type, frozenset()):  # type: ignore[arg-type]
+        return False
+    if job_type == "batch-evaluation" and status != NOT_FOUND_STATUS and not record.get("resultsFetched"):
+        return False
+    return not (job_type == "ab-test" and status != NOT_FOUND_STATUS and not record.get("failureReason"))