elan-agentkit-runtime 0.1.0__py3-none-any.whl

agentkit_runtime/builder.py

@@ -0,0 +1,448 @@
+"""Turn a discovered target into a runnable ADK App.
+
+Agents and workflows share the entire stack — Runner, plugins, session service,
+artifact service. In ADK 2.0 ``BaseAgent`` subclasses ``BaseNode`` and ``App``'s
+validator accepts either, so a ``Workflow`` drops into ``root_agent`` unchanged.
+This module is the only place that branches on ``kind``.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from typing import Any
+
+from agentkit_core.manifest import BaseTargetManifest, ToolBinding, WorkflowManifest
+from google.adk.apps import App
+from google.adk.apps._configs import EventsCompactionConfig, ResumabilityConfig
+from google.adk.tools.agent_tool import AgentTool
+
+from agentkit_runtime.config import Settings
+from agentkit_runtime.registry import Target
+
+logger = logging.getLogger(__name__)
+
+
+def mcp_url_env_var(ref: str) -> str:
+    """`echo` -> `MCP_ECHO_URL`."""
+    return f"MCP_{ref.replace('-', '_').upper()}_URL"
+
+
+def resolve_tool_url(binding: ToolBinding) -> str:
+    """Where this application actually lives.
+
+    The manifest carries a local-development default; the environment overrides
+    it per deployment. That keeps deployment addresses out of source without
+    making a target unrunnable on a laptop.
+    """
+    override = os.environ.get(mcp_url_env_var(binding.ref))
+    url = override or binding.url
+    if not url:
+        raise ValueError(
+            f"tool {binding.ref!r} has no url: set it in the manifest for local "
+            f"development, or {mcp_url_env_var(binding.ref)} in the environment"
+        )
+    return url
+
+
+def build_tools(manifest: BaseTargetManifest) -> list[Any]:
+    """Turn the manifest's tool bindings into ADK toolsets."""
+    tools: list[Any] = []
+
+    for binding in getattr(manifest, "tools", []):
+        if binding.kind != "mcp":
+            raise ValueError(
+                f"{manifest.slug}: tool kind {binding.kind!r} is not supported yet"
+            )
+
+        # Imported here, not at module scope: google-adk wraps its MCP imports
+        # in a try/except, so a missing or wrong-major `mcp` makes McpToolset
+        # silently absent rather than raising. Failing at build time names the
+        # agent that wanted it.
+        from google.adk.tools.mcp_tool import (
+            McpToolset,
+            StreamableHTTPConnectionParams,
+        )
+
+        tools.append(
+            McpToolset(
+                connection_params=StreamableHTTPConnectionParams(
+                    url=resolve_tool_url(binding)
+                ),
+                # None means "every tool the server offers". Naming them pins
+                # the agent's surface, so a new tool on a shared application
+                # does not silently appear in an unrelated agent's prompt.
+                tool_filter=binding.tool_filter,
+            )
+        )
+
+    return tools
+
+
+class WorkflowTool(AgentTool):
+    """A workflow, offered to an agent as a tool it can call.
+
+    ADK's own `AgentTool` already runs a sub-agent in-process and a `Workflow`
+    IS an agent, so almost all of this is inherited. What it cannot do is read a
+    graph's inputs: `agent_tool._get_input_schema` handles an `LlmAgent` and
+    then falls through to `agent.sub_agents`, which a `Workflow` does not have —
+    so wrapping one in a plain AgentTool raises
+
+        AttributeError: 'Workflow' object has no attribute 'sub_agents'
+
+    before it can offer the tool at all. Overriding the declaration is therefore
+    not an optimisation; it is the thing that makes this work.
+
+    The schema comes from the callee's own manifest, so the model is offered the
+    workflow's declared inputs as typed parameters rather than the bare
+    `request: string` AgentTool falls back to — which is the exact prose-packing
+    that declaring inputs was meant to remove.
+
+    `tests/test_agent_tools.py` pins both halves. If a later ADK teaches
+    `_get_input_schema` about Workflow, this class can go.
+    """
+
+    def _get_declaration(self) -> Any:
+        schema = getattr(self.agent, "input_schema", None)
+        if schema is None:
+            # Never delegate: super() raises on a Workflow rather than falling
+            # back, so an empty schema has to be a clear error of our own.
+            raise ValueError(
+                f"{self.agent.name}: a workflow offered as a tool must declare "
+                "inputs in its manifest, or the calling model has no parameters "
+                "to fill in"
+            )
+
+        from google.adk.tools import _automatic_function_calling_util
+
+        declaration = _automatic_function_calling_util.build_function_declaration(
+            func=schema, variant=self._api_variant
+        )
+        declaration.name = self.name
+        declaration.description = self.agent.description or self.agent.name
+        return declaration
+
+
+def workflow_tool(slug: str, settings: Settings) -> WorkflowTool:
+    """Resolve another target by slug and hand it back as a callable tool.
+
+    The callee is built from ITS OWN manifest — its inputs, its node overrides,
+    its model — so a workflow behaves identically whether the portal launched it
+    or an agent called it. That also means the caller's container must contain
+    the callee's code, which it does: one image holds every target.
+    """
+    from agentkit_runtime.registry import resolve
+
+    target = resolve(slug, settings)
+    if not isinstance(target.manifest, WorkflowManifest):
+        raise ValueError(f"{slug!r} is an agent, not a workflow; use its MCP tools")
+
+    ctx = BuildContext(manifest=target.manifest, settings=settings)
+    root = target.build(ctx)
+    # The description is what the calling model reads to decide whether this is
+    # the right tool, so it comes from the manifest rather than being restated.
+    root.description = target.manifest.description
+    # The same model the graph already validates its launch state against, now
+    # doing double duty as the tool's parameter list. One declaration, so the
+    # form the model fills in cannot drift from the state the nodes bind.
+    root.input_schema = target.manifest.state_model()
+
+    # ADK assumes every non-LlmAgent it is handed has `sub_agents`. Both
+    # `_get_input_schema` and `_get_output_schema` probe it, and a Workflow does
+    # not declare the field — so without this the tool raises
+    #
+    #     AttributeError: 'Workflow' object has no attribute 'sub_agents'
+    #
+    # not only when declaring itself but again inside `run_async`, i.e. at the
+    # moment the model actually calls it. Overriding the declaration alone fixes
+    # the first and leaves the second, which fails as a run-time error in front
+    # of a user rather than at build time.
+    #
+    # `object.__setattr__` because pydantic refuses an undeclared field. The
+    # value is true — a graph has no sub-agents — and it makes both helpers
+    # return None, so `run_async` JSON-dumps the arguments into the message that
+    # the first node parses.
+    object.__setattr__(root, "sub_agents", [])
+
+    # include_plugins=False, deliberately.
+    #
+    # ADK's default re-runs the caller's plugins for the nested invocation, and
+    # this platform's plugins are not re-entrant: the ledger plugin opens a
+    # SECOND hold on `before_run_callback` that nothing ever settles, so a
+    # single check-in left an orphaned reservation behind for the sweeper to
+    # expire. Measured on one conversation: four model calls, three holds, two
+    # settles.
+    #
+    # The nested run is part of the caller's invocation, not a new one — and
+    # this platform's own rule is that the invocation is the unit of
+    # idempotency, billing and tracing. So the caller's hold covers it, and its
+    # `max_llm_calls` still bounds the nested run because ADK forwards the
+    # caller's run_config.
+    #
+    # The cost is that the workflow's own model calls are missing from the
+    # invocation summary's `llm_calls`, and its nodes emit no typing status.
+    # Under-reported telemetry is the better failure of the two.
+    return WorkflowTool(agent=root, include_plugins=False)
+
+
+@dataclass(frozen=True)
+class BuildContext:
+    """Everything a target's ``build()`` is allowed to depend on.
+
+    Deliberately narrow: a target should not reach for global state, so anything
+    it needs (its own manifest, resolved settings) is handed to it explicitly.
+    """
+
+    manifest: BaseTargetManifest
+    settings: Settings
+
+    @property
+    def slug(self) -> str:
+        return self.manifest.slug
+
+    def tools(self) -> list[Any]:
+        """The manifest's tool bindings, resolved to ADK toolsets.
+
+        A target calls this from build() rather than receiving tools
+        pre-attached, so an agent that wants to wrap or reorder them can.
+        """
+        return build_tools(self.manifest)
+
+    def workflow_tool(self, slug: str) -> Any:
+        """Another target's graph, as a tool this agent can call.
+
+        The agent declares WHICH workflow; the workflow keeps declaring its own
+        inputs. Neither restates the other.
+        """
+        return workflow_tool(slug, self.settings)
+
+    def state_schema(self) -> Any:
+        """The manifest's declared inputs as a Pydantic model, or None.
+
+        Pass it to ``Workflow(state_schema=ctx.state_schema())``. ADK then
+        refuses at construction time to build a graph whose FunctionNode asks
+        for a parameter the manifest never declared — which is the whole reason
+        the schema is derived from the declaration rather than written twice.
+        """
+        if isinstance(self.manifest, WorkflowManifest):
+            return self.manifest.state_model()
+        return None
+
+    @property
+    def model(self) -> str:
+        """The manifest's model, unless local development substitutes one.
+
+        A PLAIN STRING, AND THE AGENT'S SDK CALLS THE PROVIDER DIRECTLY. There
+        was briefly a gateway in this path — `ctx.model` returned a `Gemini`
+        subclass whose client pointed at us — and it was removed because it
+        bought less than it cost:
+
+            IT ONLY EVER COVERED GEMINI. ADK resolves a bare string through
+            `LLMRegistry`, which knows Gemini and nothing else; a tenant using
+            OpenAI writes `LiteLlm(model="openai/gpt-4o")` in their own agent
+            code, which never passes through here. So the control applied to
+            one provider and silently not to the others.
+
+            IT PUT US ON THE CRITICAL PATH of every model call, and made
+            streaming, tool calling and multimodal our problem to keep faithful
+            across two SDK protocols.
+
+            UNDER BYOK THE PROVIDER BILLS THE TENANT DIRECTLY, so the budget it
+            enforced was the tenant's own guard rail rather than anything
+            protecting the platform or their neighbours.
+
+        WHAT REPLACED IT IS A NETWORK CONTROL, which is stronger for the one
+        thing that mattered: the tenant's egress allowlist is DERIVED from
+        `llm.models`, so a pod can reach the providers of the models it
+        declared and no others. That holds whatever SDK the agent uses,
+        including one we have never heard of.
+
+        MODEL_OVERRIDE RAISES rather than warns outside local development. A
+        warning was the previous behaviour and it is not enough: the
+        deploy-time cross-check asserts `MANIFEST.model` is a member of the
+        tenant's `llm.models`, and MODEL_OVERRIDE substitutes the model AFTER
+        that check passed. The console then shows one model, the agent calls
+        another, and the allowlist the tenant agreed to describes a value
+        nothing uses — with a log line nobody reads as the only trace.
+
+        That matters more now, not less: with the allowlist enforced as an
+        egress rule derived from `llm.models`, an overridden model whose
+        provider is not in that set fails as a connection timeout rather than
+        as a policy refusal.
+        """
+        if self.settings.model_override:
+            if self.settings.agentkit_env != "local":
+                raise ValueError(
+                    "MODEL_OVERRIDE is set outside local development. It substitutes "
+                    f"{self.manifest.slug}'s manifest model after the deploy-time "
+                    "model allowlist has already been checked, so the allowlist would "
+                    "no longer describe what runs. Set AGENTKIT_ENV=local to use it."
+                )
+            logger.warning(
+                "MODEL_OVERRIDE=%s is shadowing %s's manifest model — local dev only",
+                self.settings.model_override,
+                self.manifest.slug,
+            )
+            return self.settings.model_override
+        return getattr(self.manifest, "model", "gemini-flash-latest")
+
+
+def _apply_node_overrides(root: Any, manifest: WorkflowManifest) -> None:
+    """Apply per-node timeout/retry from the manifest onto the built graph.
+
+    Operational knobs belong in the manifest (inspectable, versioned, used by CI)
+    while topology stays in code, so they are stitched together here.
+    """
+    if not manifest.nodes:
+        return
+    graph = getattr(root, "graph", None)
+    nodes = list(getattr(graph, "nodes", []) or [])
+    by_name = {getattr(n, "name", None): n for n in nodes}
+
+    unknown = set(manifest.nodes) - set(by_name)
+    if unknown:
+        raise ValueError(
+            f"{manifest.slug}: manifest.nodes names not in the graph: {sorted(unknown)}"
+        )
+
+    for name, override in manifest.nodes.items():
+        node = by_name[name]
+        if override.timeout is not None:
+            node.timeout = override.timeout
+        if override.max_attempts is not None:
+            from google.adk.workflow import RetryConfig
+
+            node.retry_config = RetryConfig(max_attempts=override.max_attempts)
+
+
+def app_name_of(slug: str, settings: Settings) -> str:
+    """ADK's `app_name` for this target — the column every session is keyed on.
+
+    TENANT-QUALIFIED WHEN THERE IS A TENANT (ADR-0054, finally applied in
+    ADR-0145). `AgentRef.app_name` has composed `<tenant>.<project>.<agent>`
+    since ADR-0054 and TWO READERS HAVE ALWAYS ASKED FOR IT — rt-service's two
+    session routes, and the IAM condition that scopes a tenant's artifact
+    bucket to its own prefix — while this function passed the bare slug. So
+    both routes answered 404 for every tenant, and the artifact grant named a
+    prefix nothing wrote to. Measured on np: a pod carrying `TENANT_SLUG=rsl`
+    and `PROJECT_SLUG=salmon` wrote `app_name = 'fish-facts'`.
+
+    IT ORPHANS EVERY SESSION WRITTEN UNDER THE OLD NAME, because ADK keys a
+    session on `(app_name, user_id, id)`. `scripts/migrate_app_name.py` renames
+    the four ADK tables that carry it, and must be run after deploying this —
+    deploy FIRST, so anything the outgoing image writes in the gap is swept up
+    by the same pass.
+
+    THE BARE SLUG SURVIVES WHERE THERE IS NO TENANT, which is local
+    development and the whole test suite. Same condition `fleet.py` already
+    uses to decide whether it can derive subscription names, and for the same
+    reason: there is nothing to derive from.
+    """
+    if settings.tenant_slug and settings.project_slug:
+        from agentkit_core.identity import AgentRef  # noqa: PLC0415
+
+        return AgentRef(settings.tenant_slug, settings.project_slug, slug).app_name
+    return slug
+
+
+def build_app(target: Target, settings: Settings, plugins: list[Any] | None = None) -> App:
+    """Build the ADK App for this container's target."""
+    manifest = target.manifest
+    ctx = BuildContext(manifest=manifest, settings=settings)
+    root = target.build(ctx)
+
+    resumability = None
+    if isinstance(manifest, WorkflowManifest):
+        # A declaration nothing enforces is a comment. ADK does the enforcing,
+        # but only if the graph was constructed WITH the schema — and it cannot
+        # be attached here after the fact, because pydantic's model_post_init
+        # does not re-run on assignment and the validation would silently not
+        # happen.
+        if manifest.inputs and getattr(root, "state_schema", None) is None:
+            raise ValueError(
+                f"{manifest.slug}: the manifest declares inputs but the graph has no "
+                f"state_schema. Pass state_schema=ctx.state_schema() to Workflow(...), "
+                f"or nothing checks that the nodes' parameters match the launch form."
+            )
+        _apply_node_overrides(root, manifest)
+        if manifest.max_concurrency is not None:
+            root.max_concurrency = manifest.max_concurrency
+        if manifest.resumable:
+            # Lets the workflow pause on a long-running tool and resume from the
+            # last event, which is what keeps a human-approval step from having
+            # to hold a push request open past the 600s ack deadline.
+            resumability = ResumabilityConfig(is_resumable=True)
+
+    return App(
+        name=app_name_of(manifest.slug, settings),
+        root_agent=root,
+        plugins=plugins or [],
+        resumability_config=resumability,
+        events_compaction_config=_compaction(
+            manifest, root, target.module_name.rpartition(".")[0]),
+    )
+
+
+def _compaction(manifest, root, package: str = "") -> EventsCompactionConfig | None:
+    """`MANIFEST.compaction`, as ADK's config — or None, which is the default.
+
+    NO SUMMARIZER IS PASSED, AND THAT IS THE DESIGN. ADK builds one from the
+    root agent's own model, which is the model `cross_check` already validated
+    against `elan.yaml`'s `llm.models`. Passing our own would introduce a
+    second model into a path that has exactly one rule about models.
+
+    THE `LlmAgent` CHECK IS HERE BECAUSE ADK'S IS IN THE WRONG PLACE. Its
+    `_ensure_compaction_summarizer` raises when the root is not an `LlmAgent`,
+    from inside the POST-INVOCATION hook — and the runner notifies and
+    re-raises, so the agent answers correctly, the caller sees the reply, and
+    then the run is marked failed. Every time, once the threshold is reached.
+
+    A `WorkflowManifest` has no `compaction` field at all, so the only way to
+    reach this is an agent whose `build()` returns something other than an
+    `LlmAgent` — a `SequentialAgent`, a custom `BaseAgent`. Refusing at pod
+    start is not as good as refusing the deploy, which is not possible without
+    running `build()` in the builder; it is much better than a run that fails
+    after it has answered.
+    """
+    wanted = getattr(manifest, "compaction", None)
+    if wanted is None:
+        return None
+
+    from google.adk.agents.llm_agent import LlmAgent  # noqa: PLC0415
+
+    summarizer = None
+    if wanted.summarizer:
+        from google.adk.apps.base_events_summarizer import (  # noqa: PLC0415
+            BaseEventsSummarizer,
+        )
+
+        from agentkit_runtime.tenant_plugins import load_one  # noqa: PLC0415
+
+        summarizer = load_one(wanted.summarizer, package,
+                              expect=BaseEventsSummarizer,
+                              what="compaction summarizer")
+
+    # A DECLARED SUMMARISER MAKES THE ROOT'S TYPE IRRELEVANT, which is ADK's
+    # own rule rather than a concession: `_ensure_compaction_summarizer`
+    # returns early when one is set and never asks what the root is. So the
+    # check below guards only the case where ADK would have to derive one.
+    if summarizer is None and not isinstance(root, LlmAgent):
+        raise ValueError(
+            f"{manifest.slug}: compaction is configured, but build() returned "
+            f"a {type(root).__name__} rather than an LlmAgent. ADK builds the "
+            "summariser from the root agent's own model and has none to use "
+            "here — and it would raise AFTER an invocation had already "
+            "answered, failing a run that worked. Remove the compaction block, "
+            "or return an LlmAgent as the root."
+        )
+
+    # PASSED AS PAIRS, because ADK validates them that way and the manifest
+    # has already refused half of one.
+    return EventsCompactionConfig(
+        summarizer=summarizer,
+        token_threshold=wanted.after_tokens,
+        event_retention_size=wanted.keep_recent_events,
+        compaction_interval=wanted.after_invocations,
+        overlap_size=wanted.overlap,
+    )

agentkit_runtime/concurrency.py

@@ -0,0 +1,46 @@
+"""Per-container invocation concurrency.
+
+Push subscriptions have no ``max_outstanding_messages`` — that knob is pull-only.
+For push the throttle is Cloud Run concurrency x max-instances plus returning 429
+so Pub/Sub redelivers with exponential backoff. This is the in-process half.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import asynccontextmanager
+
+from agentkit_core.errors import SaturatedError
+
+
+class InvocationLimiter:
+    """Bounded concurrent invocations, with a short wait before shedding load.
+
+    The brief wait matters: without it a burst that would clear in milliseconds
+    turns into a redelivery round-trip. Past the deadline we shed rather than
+    queue, because a queued push message is one that will hit its ack deadline.
+    """
+
+    def __init__(self, max_concurrent: int, acquire_timeout_s: float = 2.0) -> None:
+        self._semaphore = asyncio.Semaphore(max_concurrent)
+        self._acquire_timeout_s = acquire_timeout_s
+        self.max_concurrent = max_concurrent
+        self._in_flight = 0
+
+    @property
+    def in_flight(self) -> int:
+        return self._in_flight
+
+    @asynccontextmanager
+    async def slot(self):
+        try:
+            await asyncio.wait_for(self._semaphore.acquire(), timeout=self._acquire_timeout_s)
+        except TimeoutError as exc:
+            raise SaturatedError(f"all {self.max_concurrent} invocation slots busy") from exc
+
+        self._in_flight += 1
+        try:
+            yield
+        finally:
+            self._in_flight -= 1
+            self._semaphore.release()

agentkit_runtime/config.py

@@ -0,0 +1,188 @@
+"""Runtime settings.
+
+Discipline rule from the plan: no GCP project id, region, bucket name, topic
+prefix or database name is ever a literal in source. They arrive as environment
+variables, rendered from config/platform.yaml.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+def _default_targets_root() -> Path:
+    # <repo>/agent-pipeline/runtime/src/agentkit_runtime/config.py -> <repo>/agent-pipeline
+    return Path(__file__).resolve().parents[3]
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+
+    # --- which target(s) this container is ---
+    target_slug: str = ""
+    """ONE target. The isolated case, and what every rendered pod sets today.
+
+    Kept beside `target_slugs` rather than replaced by it because the two say
+    different things to whoever reads the ConfigMap: one pod running one agent
+    is the ordinary case and should not have to look like a degenerate list."""
+
+    target_slugs: str = ""
+    """SEVERAL targets, comma separated — a GROUP sharing one workload
+    (ADR-0064).
+
+    A group exists because Autopilot bills every pod at a 250m/512Mi floor
+    whatever it requests, so five small agents cost 2.5 vCPU before doing any
+    work. Sharing a pod trades independent scaling and rollback for that.
+
+    NAMES ONLY. Everything else a member needs — its subscriptions, its dead
+    letter topic — is DERIVED from `AgentRef`, so adding a target to a group
+    does not mean adding three more environment variables that can disagree
+    with each other."""
+    build_sha: str = "dev"
+    targets_root: Path = _default_targets_root()
+
+    # --- persistence ---
+    database_url: str = ""
+    """SQLAlchemy async URL, e.g. postgresql+asyncpg://... Empty -> in-memory sessions."""
+
+    artifact_bucket: str = ""
+    """Empty -> in-memory artifact service (local dev)."""
+
+    # --- messaging ---
+    broker: str = "auto"
+    """Which message broker to use: auto, gcp or memory. `auto` picks gcp when
+    PUBSUB_PROJECT_ID is set and memory otherwise — the historical behaviour.
+    Name it explicitly on a cloud that has no project id, or `auto` degrades to
+    in-memory and the runtime looks healthy while publishing nowhere."""
+
+    pubsub_project_id: str = ""
+
+    tenant_slug: str = ""
+    """Which tenant owns this agent. Empty in local development, where there is
+    only one. Names the per-tenant event topic and the agent's namespace."""
+
+    project_slug: str = ""
+    """Which project owns this agent (ADR-0054). Empty in local development.
+
+    WITHOUT IT A POD CANNOT NAME ITS OWN TOPICS. Every provisioned name is
+    `<tenant>.<project>.<agent>`, so a runtime holding only the tenant can
+    derive none of them — which is how the dead-letter topic came to default to
+    `agent.invoke.<agent>.dlq`, a name nothing ever created. Poison messages
+    could not be forwarded at all."""
+
+    events_topic: str = "agent.events"
+    """PER TENANT in a cluster (`agent.events.<tenant>`), rendered into the pod's
+    config by the deploy service.
+
+    The shared default is local development only. Shared was a cross-tenant
+    integrity hole: every agent published to one topic and the consumers trusted
+    the envelope's `tenant_id`, so one tenant's agent could write another's audit
+    trail. Pub/Sub attaches no publisher identity, so no consumer-side check can
+    close it — per-tenant topics make publish IAM the boundary instead."""
+
+    dlq_topic: str = ""
+    """Defaults to agent.invoke.<slug>.dlq when unset."""
+
+    # --- pull consumption ---
+    invoke_subscription: str = ""
+    """The subscription this process pulls invocations from. EMPTY MEANS DO NOT
+    CONSUME, which is the local-development path: the runtime is driven through
+    POST /invoke and the push routes instead."""
+
+    resume_subscription: str = ""
+    """Where a paused run's answer arrives. A tool confirmation pauses plain
+    AGENTS too, not only workflows, so every target has one."""
+
+    # --- push auth (unset locally) ---
+    push_transport: str = "auto"
+    """Which push transport the runtime receives on: auto or gcp. `auto`
+    means gcp — unlike the broker there is no value whose presence implies a
+    cloud, so this is named rather than inferred."""
+
+    push_sa_email: str = ""
+    expected_audience: str = ""
+    """LOCAL DEVELOPMENT ONLY now. In a cluster, invocations arrive by pull and
+    there is no audience to verify — which is precisely the failure class pull
+    removed: an EXPECTED_AUDIENCE that had to change in the same move a
+    subscription repointed, or every invocation 403s and retries forever."""
+
+    # --- internal services ---
+    ledger_service_url: str = ""
+    observability_service_url: str = ""
+
+    actions_service_url: str = ""
+    """Where a tenant's autonomy rules live. Empty means the manifest decides
+    on its own — which is safe, because a manifest can only be less permissive
+    than a grant somebody added on top of it."""
+
+    # --- model ---
+    google_cloud_project: str = ""
+    google_cloud_location: str = ""
+
+    agentkit_env: str = ""
+    """Which environment this runtime is in. `local` unlocks development-only
+    behaviour; anything else, INCLUDING EMPTY, does not.
+
+    Empty is the safe default on purpose: a pod that never sets this is a
+    production pod, so forgetting the variable refuses the unsafe path rather
+    than enabling it. `AGENTKIT_` is a reserved env prefix, so a tenant cannot
+    set this through `env:` in their elan.yaml.
+    """
+
+    model_override: str = ""
+    """LOCAL DEV ONLY, and REFUSED unless `agentkit_env == "local"`.
+
+    Substitutes the manifest's model so a model-availability problem can be
+    diagnosed without editing an agent. It is not merely discouraged in a
+    deployment — it is a hole. A tenant's elan.yaml may set `env:`, and the
+    deploy-time cross-check asserts `MANIFEST.model` is a member of
+    `llm.models`; MODEL_OVERRIDE substitutes the model AFTER that check has
+    passed. So the console shows one model, the agent runs another, and the
+    allowlist the tenant agreed to is a statement about a value nothing uses.
+
+    MODEL_OVERRIDE is also in RESERVED_ENV_NAMES, which is the deploy-time and
+    admission-time half of the same rule. This is the runtime half, and it is
+    the one that still holds if a pod reaches the cluster by some other path.
+    """
+
+    @property
+    def slugs(self) -> list[str]:
+        """Every target this process runs, in declaration order.
+
+        ORDER IS PRESERVED rather than sorted, because it is the order a group
+        was declared in and a reader comparing a log line to their elan.yaml
+        should not have to re-sort it in their head.
+
+        BOTH SET AND DISAGREEING IS AN ERROR, not a precedence rule. A pod with
+        `TARGET_SLUG=a` and `TARGET_SLUGS=b,c` has been rendered by two
+        different code paths that believe different things, and quietly
+        preferring one runs an agent nobody asked for while the other is never
+        consumed — its queue growing with nothing reporting it.
+        """
+        listed = [s.strip() for s in self.target_slugs.split(",") if s.strip()]
+        single = self.target_slug.strip()
+        if listed and single and [single] != listed:
+            raise ValueError(
+                f"TARGET_SLUG is {single!r} but TARGET_SLUGS is "
+                f"{', '.join(listed)!r}. Set one or the other."
+            )
+        if listed:
+            duplicates = {s for s in listed if listed.count(s) > 1}
+            if duplicates:
+                # TWO ENGINES ON ONE SUBSCRIPTION would each lease a share of
+                # the same messages, so half an agent's invocations would be
+                # run by its own duplicate — which looks like nothing wrong.
+                raise ValueError(
+                    f"TARGET_SLUGS names {', '.join(sorted(duplicates))} more "
+                    "than once."
+                )
+            return listed
+        return [single] if single else []
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()