agent-learning-kit 0.1.0__py3-none-any.whl

fi/alk/harness/job.py

@@ -0,0 +1,426 @@
+"""Versioned job and runtime contracts for the complete ALK harness workflow.
+
+These contracts are control-plane neutral.  A local CLI creates the same ``HarnessJob`` as the
+platform hosted-job API.  The platform may enqueue it, but only an ALK executor interprets its
+stages.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Protocol
+
+from pydantic import BaseModel, Field, JsonValue, model_validator
+
+from fi.simulate.runtime.spec import RuntimeIsolation, RuntimeRequirements, SecretRef
+
+from .github import parse_github_location
+
+HARNESS_JOB_SCHEMA_VERSION = "futureagi.harness-job.v1"
+MAX_HOSTED_SCENARIO_COUNT = 200
+
+
+class ExecutionMode(str, Enum):
+    LOCAL = "local"
+    HOSTED = "hosted"
+
+
+class SourceKind(str, Enum):
+    LOCAL_REPOSITORY = "local_repository"
+    GITHUB = "github"
+    ARCHIVE = "archive"
+    IMAGE = "image"
+    REMOTE = "remote"
+    PROVIDER = "provider"
+
+
+class SourceVisibility(str, Enum):
+    PRIVATE = "private"
+    PUBLIC = "public"
+
+
+class RepositorySource(BaseModel):
+    kind: SourceKind
+    local_path: str | None = None
+    installation_id: str | None = None
+    repository: str | None = None
+    ref: str | None = None
+    commit_sha: str | None = None
+    visibility: SourceVisibility = SourceVisibility.PRIVATE
+    archive_artifact_id: str | None = None
+    image: str | None = None
+    endpoint: str | None = None
+
+    @model_validator(mode="after")
+    def _required_locator(self) -> "RepositorySource":
+        # A connected provider agent is itself the source of truth. Its ID lives
+        # in AgentConnection.config and its definition is fetched with the
+        # run-scoped provider credential during authoring, so no repository
+        # locator is required.
+        if self.kind is SourceKind.PROVIDER:
+            return self
+        if self.kind is SourceKind.GITHUB and self.repository:
+            location = parse_github_location(self.repository)
+            if self.ref and location.ref and self.ref != location.ref:
+                raise ValueError("github_ref_conflicts_with_repository_url")
+            object.__setattr__(self, "repository", location.repository)
+            object.__setattr__(self, "ref", location.ref or self.ref)
+        required = {
+            SourceKind.LOCAL_REPOSITORY: self.local_path,
+            SourceKind.GITHUB: self.repository
+            and (self.visibility is SourceVisibility.PUBLIC or self.installation_id),
+            SourceKind.ARCHIVE: self.archive_artifact_id,
+            SourceKind.IMAGE: self.image,
+            SourceKind.REMOTE: self.endpoint,
+        }[self.kind]
+        if not required:
+            raise ValueError(f"source_locator_missing: {self.kind.value}")
+        if self.kind is SourceKind.GITHUB and self.commit_sha:
+            normalized = self.commit_sha.lower()
+            if len(normalized) != 40 or any(
+                char not in "0123456789abcdef" for char in normalized
+            ):
+                raise ValueError("github_commit_sha_invalid")
+        return self
+
+
+class AgentConnection(BaseModel):
+    connector: str
+    mode: "ProviderExecutionMode | None" = None
+    config: dict[str, JsonValue] = Field(default_factory=dict)
+    secret_refs: dict[str, SecretRef] = Field(default_factory=dict)
+
+    @model_validator(mode="after")
+    def _provider_mode_is_explicit_and_safe(self) -> "AgentConnection":
+        connector = self.connector.strip().lower()
+        provider_connector = "retell" if connector == "retell_chat" else connector
+        if self.mode is ProviderExecutionMode.ENVIRONMENT_BACKED:
+            if connector == "retell_chat":
+                raise ValueError("retell_chat_environment_backed_not_supported")
+            if provider_connector not in {"vapi", "retell"}:
+                raise ValueError("environment_backed_requires_vapi_or_retell")
+            manifest = str(self.config.get("lifecycle_manifest") or "alk.yaml")
+            if manifest.startswith("/") or ".." in manifest.split("/"):
+                raise ValueError("provider_lifecycle_manifest_must_be_source_relative")
+            forbidden = {"assistant_id", "agent_id"} & set(self.config)
+            if forbidden:
+                raise ValueError(
+                    "environment_backed_target_is_provision_output: "
+                    + ", ".join(sorted(forbidden))
+                )
+        elif self.mode is ProviderExecutionMode.PROVIDER_IMPORT:
+            if provider_connector not in {"vapi", "retell"}:
+                raise ValueError("provider_import_requires_vapi_or_retell")
+            target_key = {"vapi": "assistant_id", "retell": "agent_id"}[
+                provider_connector
+            ]
+            if not str(self.config.get(target_key) or "").strip():
+                raise ValueError(f"provider_import_requires_{target_key}")
+            for path_key in ("event_path", "tool_path"):
+                value = str(self.config.get(path_key) or "")
+                if value and (
+                    not value.startswith("/")
+                    or value.startswith("//")
+                    or ".." in value.split("/")
+                ):
+                    raise ValueError(f"provider_import_{path_key}_invalid")
+        elif self.mode is ProviderExecutionMode.CONNECT_ONLY:
+            target_key = {"vapi": "assistant_id", "retell": "agent_id"}.get(
+                provider_connector
+            )
+            if target_key and not str(self.config.get(target_key) or "").strip():
+                raise ValueError(f"connect_only_requires_{target_key}")
+        elif self.mode is not None and provider_connector not in {"vapi", "retell"}:
+            raise ValueError("provider_mode_only_supported_for_vapi_or_retell")
+        return self
+
+
+class ProviderExecutionMode(str, Enum):
+    """How a provider-hosted target enters a harness run.
+
+    ``None`` on :class:`AgentConnection` preserves existing LiveKit/HTTP jobs and legacy
+    connector-only payloads. New Vapi/Retell submissions must choose one of these modes.
+    """
+
+    CONNECT_ONLY = "connect_only"
+    ENVIRONMENT_BACKED = "environment_backed"
+    PROVIDER_IMPORT = "provider_import"
+
+
+class ArtifactLevel(str, Enum):
+    METADATA_ONLY = "metadata-only"
+    TRACES = "traces"
+    TRACES_AND_RECORDINGS = "traces-and-recordings"
+    FULL = "full"
+    LOCAL_ONLY = "local-only"
+
+
+class HarnessArtifactPolicy(BaseModel):
+    level: ArtifactLevel = ArtifactLevel.TRACES
+    retention_days: int | None = Field(default=30, ge=1, le=3650)
+    allow_bundle_download: bool = False
+    max_artifact_bytes: int = Field(default=1_073_741_824, ge=0)
+
+
+class SandboxSecurityPolicy(BaseModel):
+    """Security invariants a provider must satisfy before executing customer code."""
+
+    untrusted_source: bool = True
+    read_only_source: bool = True
+    allow_privileged: bool = False
+    allow_host_runtime_control: bool = False
+    allowed_egress_domains: list[str] = Field(default_factory=list)
+
+
+class HarnessRetryPolicy(BaseModel):
+    """Conservative job retry policy; agent behavior is intentionally absent."""
+
+    max_infrastructure_attempts: int = Field(default=2, ge=1, le=5)
+    initial_backoff_seconds: float = Field(default=1.0, ge=0, le=60)
+    max_backoff_seconds: float = Field(default=15.0, ge=0, le=300)
+    retryable_domains: list[str] = Field(
+        default_factory=lambda: ["infrastructure", "connectivity"]
+    )
+
+    @model_validator(mode="after")
+    def _valid_retry_policy(self) -> HarnessRetryPolicy:
+        allowed = {"infrastructure", "connectivity", "platform_sync"}
+        unsupported = set(self.retryable_domains) - allowed
+        if unsupported:
+            raise ValueError("retry_domain_unsafe: " + ", ".join(sorted(unsupported)))
+        if self.max_backoff_seconds < self.initial_backoff_seconds:
+            raise ValueError("retry_backoff_invalid")
+        return self
+
+
+class HarnessJob(BaseModel):
+    schema_version: str = HARNESS_JOB_SCHEMA_VERSION
+    job_id: str
+    run_id: str
+    execution: ExecutionMode
+    source: RepositorySource
+    agent: AgentConnection
+    scenario_count: int = Field(default=10, ge=1, le=1000)
+    seed: int | None = None
+    runtime: RuntimeRequirements = Field(default_factory=RuntimeRequirements)
+    security: SandboxSecurityPolicy = Field(default_factory=SandboxSecurityPolicy)
+    retry: HarnessRetryPolicy = Field(default_factory=HarnessRetryPolicy)
+    artifacts: HarnessArtifactPolicy = Field(default_factory=HarnessArtifactPolicy)
+    platform_run_id: str | None = None
+    metadata: dict[str, JsonValue] = Field(default_factory=dict)
+
+    @model_validator(mode="after")
+    def _validate_job(self) -> HarnessJob:
+        if self.schema_version != HARNESS_JOB_SCHEMA_VERSION:
+            raise ValueError(f"harness_job_version_unsupported: {self.schema_version}")
+        if (
+            self.execution is ExecutionMode.LOCAL
+            and self.source.kind is SourceKind.GITHUB
+            and (
+                self.source.visibility is not SourceVisibility.PUBLIC
+                or self.source.installation_id
+            )
+        ):
+            # A local runner may clone public source, but it must never receive a platform
+            # GitHub installation credential. Private source is acquired by a hosted provider.
+            raise ValueError("local_job_cannot_use_private_platform_github_source")
+        if (
+            self.execution is ExecutionMode.HOSTED
+            and self.source.kind is SourceKind.LOCAL_REPOSITORY
+        ):
+            raise ValueError("hosted_job_cannot_use_local_path")
+        if self.execution is ExecutionMode.HOSTED:
+            if self.source.kind is SourceKind.IMAGE:
+                raise ValueError("image_source_not_hosted")
+            if self.source.kind is SourceKind.GITHUB and not self.source.commit_sha:
+                raise ValueError("github_commit_sha_required")
+            if self.scenario_count > MAX_HOSTED_SCENARIO_COUNT:
+                raise ValueError("hosted_scenario_count_out_of_range")
+            if self.runtime.isolation is not RuntimeIsolation.DEDICATED_VM:
+                raise ValueError("hosted_isolation_must_be_dedicated_vm")
+            if self.runtime.parallelism > self.runtime.cpu_units:
+                raise ValueError("hosted_parallelism_exceeds_cpu")
+            if self.artifacts.level is ArtifactLevel.LOCAL_ONLY:
+                raise ValueError("local_only_not_hosted")
+            for alias, reference in self.agent.secret_refs.items():
+                expected_manager = (
+                    "platform-config"
+                    if reference.purpose == "simulator_provider"
+                    else "platform-vault"
+                )
+                if reference.manager != expected_manager:
+                    raise ValueError(f"hosted_secret_manager_unsupported: {alias}")
+                if reference.purpose not in {
+                    "target_provider",
+                    "simulator_provider",
+                }:
+                    raise ValueError(f"hosted_secret_purpose_invalid: {alias}")
+            if self.security.allow_privileged:
+                raise ValueError("hosted_privileged_execution_forbidden")
+            if self.security.allow_host_runtime_control:
+                raise ValueError("hosted_runtime_control_forbidden")
+            if not self.security.read_only_source:
+                raise ValueError("hosted_source_must_be_read_only")
+        _reject_secret_fields(self.model_dump(exclude={"agent": {"secret_refs"}}))
+        return self
+
+
+class HarnessStage(str, Enum):
+    QUEUED = "queued"
+    ACQUIRING_SOURCE = "acquiring_source"
+    UNDERSTANDING_AGENT = "understanding_agent"
+    GENERATING_ENVIRONMENT = "generating_environment"
+    BUILDING_ENVIRONMENT = "building_environment"
+    VALIDATING_ENVIRONMENT = "validating_environment"
+    GENERATING_DATA = "generating_data"
+    GENERATING_SCENARIOS = "generating_scenarios"
+    VALIDATING_SCENARIOS = "validating_scenarios"
+    CONNECTING_AGENT = "connecting_agent"
+    RUNNING = "running"
+    GRADING = "grading"
+    UPLOADING_ARTIFACTS = "uploading_artifacts"
+    CLEANING_UP = "cleaning_up"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELED = "canceled"
+
+    @property
+    def terminal(self) -> bool:
+        return self in {self.COMPLETED, self.FAILED, self.CANCELED}
+
+
+class FailureDomain(str, Enum):
+    AGENT = "agent"
+    SIMULATOR = "simulator"
+    ENVIRONMENT = "environment"
+    CONNECTIVITY = "connectivity"
+    INFRASTRUCTURE = "infrastructure"
+    GRADING = "grading"
+    ARTIFACT = "artifact"
+    PLATFORM_SYNC = "platform_sync"
+
+
+class FailureOwner(str, Enum):
+    CUSTOMER_AGENT = "customer_agent"
+    FUTUREAGI = "futureagi"
+
+
+class CustomerFailure(BaseModel):
+    """Small, ownership-correct failure surface safe for customer-facing APIs."""
+
+    category: str
+    owner: FailureOwner
+    code: str
+    message: str
+    retryable: bool = False
+
+
+class HarnessFailure(BaseModel):
+    domain: FailureDomain
+    stage: HarnessStage
+    code: str
+    message: str
+    retryable: bool = False
+    details: dict[str, JsonValue] = Field(default_factory=dict)
+
+    @property
+    def owner(self) -> FailureOwner:
+        return (
+            FailureOwner.CUSTOMER_AGENT
+            if self.domain is FailureDomain.AGENT
+            else FailureOwner.FUTUREAGI
+        )
+
+    def for_customer(self) -> CustomerFailure:
+        """Do not present a harness subsystem failure as a customer-agent failure."""
+        if self.owner is FailureOwner.CUSTOMER_AGENT:
+            return CustomerFailure(
+                category="agent_failure",
+                owner=self.owner,
+                code=self.code,
+                message=self.message,
+                retryable=False,
+            )
+        return CustomerFailure(
+            category="system_failure",
+            owner=self.owner,
+            code=self.code,
+            message=(
+                "FutureAGI could not complete this run. The failure has been recorded "
+                "for diagnosis; the submitted agent has not been marked as failed."
+            ),
+            retryable=self.retryable,
+        )
+
+
+class HarnessJobStatus(BaseModel):
+    job_id: str
+    run_id: str
+    stage: HarnessStage
+    updated_at: datetime
+    detail: str | None = None
+    failure: HarnessFailure | None = None
+    environment_digest: str | None = None
+    scenario_set_digest: str | None = None
+    completed_scenarios: int = Field(default=0, ge=0)
+    total_scenarios: int = Field(default=0, ge=0)
+    attempt: int = Field(default=1, ge=1)
+
+
+class HostedHarnessPort(Protocol):
+    """Scheduler-neutral interface implemented by the hosted ALK sandbox fleet."""
+
+    async def submit(self, job: HarnessJob) -> HarnessJobStatus: ...
+
+    async def status(self, job_id: str) -> HarnessJobStatus: ...
+
+    async def cancel(self, job_id: str) -> None: ...
+
+
+_SECRET_NAMES = {
+    "api_key",
+    "api_secret",
+    "authorization",
+    "credential",
+    "credentials",
+    "password",
+    "private_key",
+    "secret",
+    "token",
+}
+
+
+def _reject_secret_fields(value: object, path: tuple[str, ...] = ()) -> None:
+    if isinstance(value, dict):
+        for key, item in value.items():
+            normalized = str(key).lower().replace("-", "_")
+            current = (*path, str(key))
+            if normalized in _SECRET_NAMES and item not in (None, "", {}, []):
+                raise ValueError("resolved_secret_forbidden: " + ".".join(current))
+            _reject_secret_fields(item, current)
+    elif isinstance(value, list):
+        for index, item in enumerate(value):
+            _reject_secret_fields(item, (*path, str(index)))
+
+
+__all__ = [
+    "HARNESS_JOB_SCHEMA_VERSION",
+    "AgentConnection",
+    "ArtifactLevel",
+    "ExecutionMode",
+    "CustomerFailure",
+    "FailureDomain",
+    "FailureOwner",
+    "HarnessArtifactPolicy",
+    "HarnessFailure",
+    "HarnessJob",
+    "HarnessJobStatus",
+    "HarnessRetryPolicy",
+    "HarnessStage",
+    "HostedHarnessPort",
+    "RepositorySource",
+    "SandboxSecurityPolicy",
+    "SourceKind",
+    "SourceVisibility",
+]

fi/alk/harness/judge.py

@@ -0,0 +1,184 @@
+"""Deciding a judged sub-goal against the world the session left behind.
+
+A judged sub-goal is one nothing observable settles, so a model reaches the verdict. Until now
+nothing did: judged sub-goals carried a placeholder check returning None, which the scheduler read
+as "held", so every one passed before anything looked. This runs in the sandbox at the end of the
+session, while the world is still alive, so the judge reads real state rather than a snapshot.
+
+Nothing here is modality-specific. It reasons over the world's tables, the actions the agent
+took and what was said, which a voice call, a typed conversation and a browser the agent drives all
+leave behind in the same shape, so the wording stays neutral rather than naming a call.
+
+A judge that cannot decide returns held None: the unjudged path the platform already skips, because
+a judge that failed to run is not evidence against the agent.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Sequence
+
+from .backends import SessionSpec, tool, tool_server
+from .config import chosen_model
+from .session import Stage
+from .tools import schema
+
+JUDGE_MODEL_ALIAS = "ALK_JUDGE_MODEL"
+_LIMIT = 600
+_TRANSCRIPT_LIMIT = 24000
+
+_INSTRUCTIONS = """
+You decide one claim about a session that already happened, against the world it left behind.
+
+Look before you answer: read the actions you were given, inspect the tables the claim touches, query
+for a specific row when the claim is about one, and read the transcript when the claim is about what
+was said. The world is the run's final state. Its SQL dialect is PostgreSQL, not SQLite. Use
+inspect_world to discover tables; do not query sqlite_master or make up a schema. A claim about
+wording or about what the agent told the caller is settled by read_transcript: do not call it
+undecided before reading it.
+
+Then call decide, once. `passed` true when the claim holds, false when it does not, and an
+explanation citing what you saw: a value, a row, an action and its arguments. An explanation that
+only restates the claim is not a verdict. If you genuinely cannot tell, pass undecided true rather
+than guess. Judge only the claim you were given.
+""".strip()
+
+
+def judge_model() -> str:
+    """The judge's model. Set ALK_JUDGE_MODEL to run it on something other than the harness model."""
+    return os.environ.get(JUDGE_MODEL_ALIAS, "").strip() or chosen_model()
+
+
+def _short(value: object) -> object:
+    if isinstance(value, str) and len(value) > _LIMIT:
+        return value[:_LIMIT] + f"... [{len(value)} chars]"
+    if isinstance(value, dict):
+        return {key: _short(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [_short(item) for item in value[:20]]
+    return value
+
+
+def _dump(value: object) -> str:
+    return json.dumps(_short(value), default=str, indent=1)
+
+
+async def judge(
+    goal: Any, world: Any, calls: Sequence[Any], *, messages: Sequence[Any] = ()
+) -> tuple[bool | None, str]:
+    """Decide one judged sub-goal: (passed, explanation). Never raises."""
+    verdict: dict[str, tuple[bool | None, str]] = {}
+
+    @tool(
+        "inspect_world",
+        "The world's tables: without a name, every table and its row count; with one, its rows.",
+        schema({"table": str}, []),
+    )
+    async def inspect_world(args: dict[str, Any]) -> dict[str, Any]:
+        table = str(args.get("table") or "").strip()
+        state = world.state(table or None)
+        if table:
+            return _say(_dump(state))
+        return _say(_dump({name: len(rows or []) for name, rows in state.items()}))
+
+    @tool(
+        "query_world",
+        "Run one read-only PostgreSQL query for a specific row. Use inspect_world for schema discovery.",
+        schema({"sql": str}, ["sql"]),
+    )
+    async def query_world(args: dict[str, Any]) -> dict[str, Any]:
+        sql = str(args.get("sql") or "")
+        try:
+            return _say(_dump(world.query(sql)))
+        except Exception as exc:  # noqa: BLE001 - bad model SQL is feedback, not a stage crash
+            return _say(
+                _dump(
+                    {
+                        "error": f"{type(exc).__name__}: {exc}",
+                        "dialect": "postgresql",
+                        "recovery": "Use inspect_world to discover real tables, then retry once.",
+                    }
+                ),
+                error=True,
+            )
+
+    @tool(
+        "read_transcript",
+        "What was said, in order. `user` is the caller, `assistant` is the agent being judged.",
+        schema({}, []),
+    )
+    async def read_transcript(args: dict[str, Any]) -> dict[str, Any]:
+        if not messages:
+            return _say(
+                "no transcript was recorded for this session, so nothing here can settle a claim "
+                "about what was said",
+                error=True,
+            )
+        return _say(_transcript(messages))
+
+    @tool(
+        "decide",
+        "Commit to the verdict, once, after looking.",
+        schema({"passed": bool, "explanation": str, "undecided": bool}, ["explanation"]),
+    )
+    async def decide(args: dict[str, Any]) -> dict[str, Any]:
+        explanation = str(args.get("explanation") or "").strip()
+        if not explanation:
+            return _say("a verdict needs an explanation naming what you saw", error=True)
+        held = None if bool(args.get("undecided")) else bool(args.get("passed"))
+        verdict["it"] = (held, explanation)
+        return _say("recorded")
+
+    spec = SessionSpec(
+        system_prompt=_INSTRUCTIONS,
+        servers={
+            "world": tool_server(
+                name="world",
+                tools=[inspect_world, query_world, read_transcript, decide],
+            )
+        },
+        max_turns=12,
+        model=judge_model(),
+    )
+    prompt = (
+        f"Claim {getattr(goal, 'name', '')!r}.\n"
+        f"What it means: {getattr(goal, 'what', '') or '(none written)'}\n"
+        f"Why a model must decide it: {getattr(goal, 'judged', '')}\n\n"
+        f"Actions the agent took:\n{_dump([_call(c) for c in calls])}\n\n"
+        "Inspect the world and the transcript as needed, then call decide."
+    )
+    try:
+        async with Stage(spec, name="judge-sub-goals") as stage:
+            await stage.say(prompt)
+    except Exception as exc:  # noqa: BLE001 - a judge that could not run is not a failed agent
+        return None, f"the judge could not run: {type(exc).__name__}: {exc}"
+    return verdict.get("it", (None, "the judge finished without a verdict"))
+
+
+def _transcript(messages: Sequence[Any]) -> str:
+    """The turns as spoken, oldest first. A long call keeps its tail, where a readback would be."""
+    body = "\n".join(
+        f"{m.get('role') or 'unknown'}: {str(m.get('content') or '').strip()}"
+        for m in messages
+        if isinstance(m, dict)
+    )
+    return body if len(body) <= _TRANSCRIPT_LIMIT else "...\n" + body[-_TRANSCRIPT_LIMIT:]
+
+
+def _call(call: Any) -> dict[str, Any]:
+    return {
+        "name": getattr(call, "name", ""),
+        "arguments": getattr(call, "arguments", None) or {},
+        "result": getattr(call, "result", None),
+        "ok": bool(getattr(call, "ok", False)),
+        "refused": bool(getattr(call, "refused", False)),
+        "error": str(getattr(call, "error", "") or ""),
+    }
+
+
+def _say(text: str, *, error: bool = False) -> dict[str, Any]:
+    body: dict[str, Any] = {"content": [{"type": "text", "text": text}]}
+    if error:
+        body["is_error"] = True
+    return body

fi/alk/harness/livekit_source.py

@@ -0,0 +1,50 @@
+"""Static LiveKit worker metadata recovered from untrusted source code."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Collection
+from pathlib import Path
+
+
+_ENV_AGENT_NAME = re.compile(
+    r"agent_name\s*=\s*os\.(?:environ\.get|getenv)\(\s*"
+    r"[\"']LIVEKIT_AGENT_NAME[\"']\s*,\s*[\"'](?P<name>[^\"']+)[\"']"
+)
+_STATIC_RTC_SESSION_AGENT_NAME = re.compile(
+    r"@(?:[A-Za-z_][A-Za-z0-9_]*\.)*rtc_session\s*\("
+    r"(?:(?!\)\s*(?:\r?\n|$)).)*?"
+    r"agent_name\s*=\s*[\"'](?P<name>[^\"']+)[\"']",
+    re.DOTALL,
+)
+
+
+def infer_livekit_agent_name_from_source(
+    source_root: Path, *, ignored_parts: Collection[str] = ()
+) -> str:
+    """Return a literal LiveKit dispatch name declared by common SDK forms.
+
+    Dynamic expressions remain unresolved deliberately: guessing could route a call to the wrong
+    worker on a shared LiveKit project.
+    """
+
+    try:
+        if not source_root.is_dir():
+            return ""
+        for path in source_root.rglob("*.py"):
+            relative = path.relative_to(source_root)
+            if any(part in ignored_parts for part in relative.parts):
+                continue
+            try:
+                source = path.read_text(encoding="utf-8")
+            except (OSError, UnicodeDecodeError):
+                continue
+            for pattern in (_ENV_AGENT_NAME, _STATIC_RTC_SESSION_AGENT_NAME):
+                if match := pattern.search(source):
+                    return match.group("name").strip()
+    except OSError:
+        pass
+    return ""
+
+
+__all__ = ["infer_livekit_agent_name_from_source"]