UncountablePythonSDK 0.0.180__py3-none-any.whl → 0.0.181__py3-none-any.whl

examples/integration-server/pyproject.toml

@@ -9,7 +9,7 @@ dependencies = [
   "ruff == 0.*",
   "openpyxl == 3.*",
   "more_itertools ==11.*",
-  "types-paramiko ==5.0.0.20260617",
+  "types-paramiko ==5.0.0.20260724",
   "types-openpyxl == 3.*",
   "types-pytz ==2026.*",
   "types-requests == 2.*",
@@ -17,7 +17,7 @@ dependencies = [
   "pandas-stubs",
   "xlrd == 2.*",
   "msgspec ==0.21.*",
-  "websockets==16.1.1",
+  "websockets==17.0",
 ]
 
 [tool.mypy]

pkgs/argument_parser/parser_inner.py

@@ -560,9 +560,23 @@ def _build_parser_dataclass(
     type_params = getattr(parsed_type, "__parameters__", None)
     cache_key: typing.Any = parsed_type
     if type_params is not None and type_var_map:
+        # WARNING: Do not widen this back to the whole `type_var_map`. Only a class's
+        # own parameters can appear in its field annotations, so only their bindings
+        # distinguish one instantiation's parser from another; the map additionally
+        # carries every enclosing generic's TypeVars, which are irrelevant here.
+        #
+        # Widening it does not merely lose cache hits. Each generic class declares its
+        # own TypeVar, so a set of mutually recursive generics contributes a distinct
+        # one per level as the build descends. Keyed on the whole map, no key ever
+        # repeats, nothing is ever reused, and parser construction grows exponentially
+        # in the number of participating generics rather than terminating.
         cache_key = (
             parsed_type,
-            tuple(type_var_map.items()),
+            tuple(
+                (param, type_var_map[param])
+                for param in type_params
+                if param in type_var_map
+            ),
         )
 
     cur_parser = context.cache.get(cache_key)

pkgs/type_spec/__main__.py

@@ -4,6 +4,7 @@ import sys
 from .config import parse_yaml_config
 from .emit_open_api import emit_open_api
 from .emit_python import emit_python
+from .emit_scss import emit_scss
 from .emit_typescript import emit_typescript
 from .load_types import load_types
 
@@ -34,6 +35,9 @@ def main() -> bool:
         if config.typescript is not None:
             emit_typescript(builder, config.typescript)
 
+        if config.scss is not None:
+            emit_scss(builder, config.scss)
+
     return True
 
 

pkgs/type_spec/actions_registry/__main__.py

@@ -93,6 +93,7 @@ def main() -> None:
                 if definition.visibility_scope is not None
                 else None,
                 kind=definition.kind,
+                search_aliases=definition.search_aliases,
                 arguments=definition.arguments,
             )
             action_definitions_with_arguments_list.append(

pkgs/type_spec/actions_registry/emit_python.py

@@ -22,6 +22,11 @@ def _module_enum_member(module: str) -> str:
     return module.upper()
 
 
+def _emit_search_aliases(search_aliases: list[str]) -> str:
+    items = ", ".join(_py_str(alias) for alias in search_aliases)
+    return f"[{items}]"
+
+
 def _emit_visibility_scope(
     visibility_scope: list[actions_registry_t.ActionDefinitionVisibilityScope],
 ) -> str:
@@ -58,6 +63,10 @@ def _emit_action_definition(
         out.write(
             f"{sub_indent}kind=actions_registry_t.ActionDefinitionKind.{action.kind.name},\n"
         )
+    if action.search_aliases is not None and len(action.search_aliases) > 0:
+        out.write(
+            f"{sub_indent}search_aliases={_emit_search_aliases(action.search_aliases)},\n"
+        )
     if action.arguments is not None:
         out.write(f"{sub_indent}arguments={_py_str(action.arguments)},\n")
     out.write(f"{indent}),\n")

pkgs/type_spec/actions_registry/emit_typescript.py

@@ -151,6 +151,13 @@ def _emit_action_definition(
         out.write(
             f"{sub_indent}kind: ActionsRegistryT.ActionDefinitionKind.{ts_name(action_definition.kind, name_case=builder.NameCase.convert)},\n"
         )
+    if (
+        action_definition.search_aliases is not None
+        and len(action_definition.search_aliases) > 0
+    ):
+        out.write(
+            f"{sub_indent}searchAliases: {_emit_search_aliases(action_definition.search_aliases)},\n"
+        )
     out.write(f"{indent}}} as ActionsRegistryT.ActionDefinition{argument_type},\n")
     return out.getvalue()
 
@@ -174,6 +181,11 @@ def _emit_action_definition_types(modules: list[str], indent: str) -> str:
     return out.getvalue()
 
 
+def _emit_search_aliases(search_aliases: list[str]) -> str:
+    aliases = ",".join(encode_common_string(alias) for alias in search_aliases)
+    return f"[ {aliases} ]"
+
+
 def _emit_visibility_scope(
     visibility_scope: list[actions_registry_t.ActionDefinitionVisibilityScope],
 ) -> str:

pkgs/type_spec/builder.py

@@ -517,7 +517,9 @@ class SpecTypeDefn(SpecType):
 class SpecTypeGenericParameter(SpecType):
     def __init__(
         self,
-        spec_type_definition: SpecTypeDefnObject | SpecTypeDefnUnion,
+        spec_type_definition: SpecTypeDefnObject
+        | SpecTypeDefnUnion
+        | SpecTypeDefnAlias,
         name: str,
     ) -> None:
         self.spec_type_definition = spec_type_definition
@@ -546,6 +548,8 @@ class SpecTypeDefnObject(SpecTypeDefn):
     base: SpecTypeDefnObject | None
     parameters: list[str]
     base_type_instance: SpecTypeInstance | None
+    # Set by _mark_recursive_instantiations; see is_eagerly_self_referential.
+    needs_lazy_emission: bool = False
 
     def __init__(
         self,
@@ -652,22 +656,26 @@ class SpecTypeDefnObject(SpecTypeDefn):
 
 class SpecTypeDefnAlias(SpecTypeDefn):
     alias: SpecType
+    parameters: list[str]
 
     def __init__(
         self,
         namespace: SpecNamespace,
         name: str,
+        *,
+        parameters: list[str] | None = None,
     ) -> None:
         super().__init__(
             namespace,
             name,
         )
+        self.parameters = parameters if parameters is not None else []
         self.desc: str | None = None
         self.discriminator: str | None = None
 
     def process(self, builder: SpecBuilder, data: RawDict) -> None:
         super().base_process(builder, data, ["type", "desc", "alias", "discriminator"])
-        self.alias = builder.parse_type(self.namespace, data["alias"])
+        self.alias = builder.parse_type(self.namespace, data["alias"], scope=self)
         self.desc = data.get("desc", None)
         self.discriminator = data.get("discriminator", None)
 
@@ -1447,19 +1455,19 @@ class SpecNamespace:
             defn_type = defn.get("type")
             assert isinstance(defn_type, str), f"{name} requires a string type"
             spec_type: SpecTypeDefn
+            named_parameters = (
+                [
+                    parameter.name
+                    for name_parameters in parsed_name.parameters
+                    for parameter in name_parameters
+                ]
+                if parsed_name.parameters is not None
+                else None
+            )
             if defn_type == DefnTypeName.s_alias:
-                spec_type = SpecTypeDefnAlias(self, name)
+                spec_type = SpecTypeDefnAlias(self, name, parameters=named_parameters)
             elif defn_type == DefnTypeName.s_union:
-                union_parameters = (
-                    [
-                        parameter.name
-                        for name_parameters in parsed_name.parameters
-                        for parameter in name_parameters
-                    ]
-                    if parsed_name.parameters is not None
-                    else None
-                )
-                spec_type = SpecTypeDefnUnion(self, name, parameters=union_parameters)
+                spec_type = SpecTypeDefnUnion(self, name, parameters=named_parameters)
             elif defn_type == DefnTypeName.s_external:
                 spec_type = SpecTypeDefnExternal(self, name)
             elif defn_type == DefnTypeName.s_new_type:
@@ -1467,19 +1475,10 @@ class SpecNamespace:
             elif defn_type == DefnTypeName.s_string_enum:
                 spec_type = SpecTypeDefnStringEnum(self, name)
             else:
-                parameters = (
-                    [
-                        parameter.name
-                        for name_parameters in parsed_name.parameters
-                        for parameter in name_parameters
-                    ]
-                    if parsed_name.parameters is not None
-                    else None
-                )
                 spec_type = SpecTypeDefnObject(
                     self,
                     name,
-                    parameters=parameters,
+                    parameters=named_parameters,
                 )
             self.types[name] = spec_type
 
@@ -1549,6 +1548,62 @@ class NameDataPair:
     data: RawDict
 
 
+def is_eagerly_self_referential(target: SpecTypeDefn, current: SpecType) -> bool:
+    """
+    Does rendering `current` name `target` in a position evaluated eagerly.
+
+    A generic instantiation renders its parameters inline (`Container[Target]`), so a
+    definition reachable that way is resolved at assignment time. Object properties are
+    deferred in both emitted languages, so this stops at object definitions rather than
+    descending into them.
+    """
+    if current is target:
+        return True
+    if isinstance(current, SpecTypeInstance):
+        return is_eagerly_self_referential(target, current.defn_type) or any(
+            is_eagerly_self_referential(target, parameter)
+            for parameter in current.parameters
+        )
+    return False
+
+
+def _collect_objects_on_cycle(
+    target: SpecTypeDefn,
+    current: SpecType,
+    found: set[SpecTypeDefnObject],
+    seen: set[int],
+) -> None:
+    """
+    Collect the objects whose instantiation is what closes the cycle back on `target`.
+
+    Only those need lazy emission. An instantiation that appears alongside them but
+    does not name `target` — `Container<String>` in the same union — is not on the
+    cycle and emits as a type alias like any other generic. The synthetic backing
+    objects of unions and lists are skipped for the same reason: they are never
+    emitted as objects.
+    """
+    if id(current) in seen:
+        return
+    seen.add(id(current))
+    if isinstance(current, SpecTypeInstance):
+        if (
+            isinstance(current.defn_type, SpecTypeDefnObject)
+            and not current.defn_type.is_base
+            and current.parameters
+            and is_eagerly_self_referential(target, current)
+        ):
+            found.add(current.defn_type)
+        _collect_objects_on_cycle(target, current.defn_type, found, seen)
+        for parameter in current.parameters:
+            _collect_objects_on_cycle(target, parameter, found, seen)
+        return
+    if isinstance(current, SpecTypeDefnAlias):
+        _collect_objects_on_cycle(target, current.alias, found, seen)
+        return
+    if isinstance(current, SpecTypeDefnUnion):
+        _collect_objects_on_cycle(target, current.get_backing_type(), found, seen)
+
+
 class SpecBuilder:
     def __init__(
         self,
@@ -1651,8 +1706,33 @@ class SpecBuilder:
             print(self.where)
             raise
 
+        self._mark_recursive_instantiations()
         return True
 
+    def _mark_recursive_instantiations(self) -> None:
+        """
+        Flag objects instantiated inside a self-referential alias or union.
+
+        TypeScript expands a generic type alias eagerly, so such an instantiation is
+        rejected as circular unless the instantiated object emits as an interface,
+        whose members resolve lazily. Only objects on that cycle need it, so the
+        remaining generics keep their existing emission.
+        """
+        for namespace in self.namespaces.values():
+            for defn in namespace.types.values():
+                if isinstance(defn, SpecTypeDefnAlias):
+                    expression: SpecType = defn.alias
+                elif isinstance(defn, SpecTypeDefnUnion):
+                    expression = defn.get_backing_type()
+                else:
+                    continue
+                if not is_eagerly_self_referential(defn, expression):
+                    continue
+                found: set[SpecTypeDefnObject] = set()
+                _collect_objects_on_cycle(defn, expression, found, set())
+                for obj in found:
+                    obj.needs_lazy_emission = True
+
     def get_type_of_literal(self, value: util.LiteralTypeValue) -> SpecType:
         if isinstance(value, str):
             return self.namespaces[base_namespace_name].types[BaseTypeName.s_string]
@@ -1708,7 +1788,9 @@ class SpecBuilder:
         if (
             defn_type is None
             and scope is not None
-            and isinstance(scope, (SpecTypeDefnObject, SpecTypeDefnUnion))
+            and isinstance(
+                scope, (SpecTypeDefnObject, SpecTypeDefnUnion, SpecTypeDefnAlias)
+            )
         ):
             if path[0].name in scope.parameters:
                 return SpecTypeGenericParameter(

pkgs/type_spec/config.py

@@ -115,6 +115,36 @@ class OpenAPIConfig(BaseLanguageConfig):
         self.types_output = os.path.abspath(self.types_output)
 
 
+@dataclass(kw_only=True)
+class ScssConstantOutput:
+    namespace: str  # namespace holding the constant to emit
+    constant: str  # nested Dict constant to flatten into $prefix-<group>-<field> vars
+    output: str  # scss file to write the flattened variables to
+    prefix: str  # variable name prefix, e.g. "unc" for $unc-<group>-<field>
+
+    def __post_init__(self: Self) -> None:
+        self.output = os.path.abspath(self.output)
+
+
+def _parse_scss_output(entry: object) -> ScssConstantOutput:
+    assert isinstance(entry, dict), (
+        f"scss config entry must be a mapping, got {entry!r}"
+    )
+    fields: dict[str, str] = {}
+    for key in ("namespace", "constant", "output", "prefix"):
+        value = entry.get(key)
+        assert isinstance(value, str), (
+            f"scss config entry requires string '{key}', got {value!r}"
+        )
+        fields[key] = value
+    return ScssConstantOutput(
+        namespace=fields["namespace"],
+        constant=fields["constant"],
+        output=fields["output"],
+        prefix=fields["prefix"],
+    )
+
+
 @dataclass(kw_only=True)
 class Config:
     top_namespace: str
@@ -124,6 +154,7 @@ class Config:
     typescript: TypeScriptConfig | None
     python: PythonConfig
     open_api: OpenAPIConfig | None
+    scss: list[ScssConstantOutput] | None
 
 
 T = TypeVar("T")
@@ -164,6 +195,14 @@ def parse_yaml_config(config_file: str) -> Config:
         else None
     )
 
+    raw_scss = raw_config.get("scss")
+    scss = None
+    if raw_scss is not None:
+        assert isinstance(raw_scss, list), (
+            f"scss config must be a list, got {raw_scss!r}"
+        )
+        scss = [_parse_scss_output(entry) for entry in raw_scss]
+
     top_namespace = raw_config["top_namespace"]
     assert isinstance(top_namespace, str)
 
@@ -174,4 +213,5 @@ def parse_yaml_config(config_file: str) -> Config:
         typescript=typescript,
         python=python,
         open_api=open_api,
+        scss=scss,
     )

pkgs/type_spec/emit_python.py

@@ -947,7 +947,14 @@ def _emit_type(ctx: Context, stype: builder.SpecType) -> None:
 
     if isinstance(stype, builder.SpecTypeDefnAlias):
         ctx.use_serial_alias = True
-        ctx.out.write(f"{stype.name} = typing.Annotated[\n")
+        if len(stype.parameters) > 0:
+            type_params = f"[{', '.join(stype.parameters)}]"
+            assignment = f"type {stype.name}{type_params}"
+        elif builder.is_eagerly_self_referential(stype, stype.alias):
+            assignment = f"type {stype.name}"
+        else:
+            assignment = stype.name
+        ctx.out.write(f"{assignment} = typing.Annotated[\n")
         ctx.out.write(f"{INDENT}{refer_to(ctx, stype.alias)},\n")
         ctx.out.write(f"{INDENT}serial_alias_annotation(\n")
         ctx.out.write(
@@ -964,6 +971,8 @@ def _emit_type(ctx: Context, stype: builder.SpecType) -> None:
         if len(stype.parameters) > 0:
             type_params = f"[{', '.join(stype.parameters)}]"
             ctx.out.write(f"type {stype.name}{type_params} = typing.Annotated[\n")
+        elif builder.is_eagerly_self_referential(stype, stype.get_backing_type()):
+            ctx.out.write(f"type {stype.name} = typing.Annotated[\n")
         else:
             ctx.out.write(f"{stype.name} = typing.Annotated[\n")
         ctx.out.write(f"{INDENT}{refer_to(ctx, stype.get_backing_type())},\n")

pkgs/type_spec/emit_scss.py

@@ -0,0 +1,42 @@
+from collections import defaultdict
+
+from . import builder, util
+from .config import ScssConstantOutput
+
+_HEADER = (
+    "// DO NOT MODIFY -- This file is generated by type_spec\n"
+    "// Edit the source constant in main/type_spec/ and run `just typespec regen-types`\n"
+)
+
+
+def emit_scss(
+    spec_builder: builder.SpecBuilder, configs: list[ScssConstantOutput]
+) -> None:
+    blocks_by_output: dict[str, list[str]] = defaultdict(list)
+    for config in configs:
+        namespace = spec_builder.namespaces[config.namespace]
+        sconst = namespace.constants[config.constant]
+        blocks_by_output[config.output].append(_render_constant(sconst, config.prefix))
+    for output, blocks in blocks_by_output.items():
+        util.rewrite_file(output, _HEADER + "\n" + "\n\n".join(blocks) + "\n")
+
+
+def _render_constant(sconst: builder.SpecConstant, prefix: str) -> str:
+    value = sconst.value
+    assert isinstance(value, dict), "scss emit expects a nested Dict constant"
+
+    blocks: list[str] = []
+    for group, shades in value.items():
+        assert isinstance(shades, dict), (
+            "scss emit expects Dict<Key, Dict|Object> values"
+        )
+        lines = [
+            f"${_scss_name(prefix, str(group), str(field))}: {color};"
+            for field, color in shades.items()
+        ]
+        blocks.append("\n".join(lines))
+    return "\n\n".join(blocks)
+
+
+def _scss_name(prefix: str, group: str, field: str) -> str:
+    return f"{prefix}-{group}-{field}".replace("_", "-")

pkgs/type_spec/emit_typescript_util.py

@@ -193,7 +193,11 @@ def emit_type_ts(ctx: EmitTypescriptContext, stype: builder.SpecType) -> None:
         return
 
     if isinstance(stype, builder.SpecTypeDefnAlias):
-        ctx.out.write(f"export type {stype.name} = {refer_to(ctx, stype.alias)}\n")
+        if len(stype.parameters) > 0:
+            full_type_name = f"{stype.name}<{', '.join(stype.parameters)}>"
+        else:
+            full_type_name = stype.name
+        ctx.out.write(f"export type {full_type_name} = {refer_to(ctx, stype.alias)}\n")
         return
 
     if isinstance(stype, builder.SpecTypeDefnUnion):
@@ -219,23 +223,36 @@ def emit_type_ts(ctx: EmitTypescriptContext, stype: builder.SpecType) -> None:
     assert isinstance(stype, builder.SpecTypeDefnObject)
     assert stype.base is not None
 
-    base_type = ""
+    base_ref = ""
+    parenthesized_base = ""
     if not stype.base.is_base:
         if stype.base_type_instance is not None:
-            base_type = f"({refer_to(ctx, stype.base_type_instance)}) & "
+            base_ref = refer_to(ctx, stype.base_type_instance)
+            parenthesized_base = f"({base_ref})"
         else:
-            base_type = f"{refer_to(ctx, stype.base)} & "
+            base_ref = refer_to(ctx, stype.base)
+            parenthesized_base = base_ref
+    base_type = f"{parenthesized_base} & " if base_ref else ""
 
     if stype.properties is None and base_type == "":
         ctx.out.write(f"export type {stype.name} = TEmpty\n")
     elif stype.properties is None:
         ctx.out.write(f"export type {stype.name} = {base_type}{{}}\n")
     else:
-        if isinstance(stype, builder.SpecTypeDefnObject) and len(stype.parameters) > 0:
+        if len(stype.parameters) > 0:
             full_type_name = f"{stype.name}<{', '.join(stype.parameters)}>"
         else:
             full_type_name = stype.name
-        ctx.out.write(f"export type {full_type_name} = {base_type}{{")
+        if stype.needs_lazy_emission:
+            # WARNING: Must not go back to a type alias. TypeScript expands a
+            # generic type alias eagerly and rejects the cycle with TS2456;
+            # interface members resolve lazily. Kept to on-cycle objects because
+            # an interface has no implicit index signature, so it is not
+            # assignable where a type alias is.
+            extends = f" extends {base_ref}" if base_ref else ""
+            ctx.out.write(f"export interface {full_type_name}{extends} {{")
+        else:
+            ctx.out.write(f"export type {full_type_name} = {base_type}{{")
         ctx.out.write("\n")
         for prop in stype.properties.values():
             ref_type = refer_to(ctx, prop.spec_type)

pkgs/type_spec/type_info/emit_type_info.py

@@ -149,7 +149,9 @@ def emit_type_info_python(build: builder.SpecBuilder, output: str) -> None:
 
     for namespace, data in type_map.namespaces.items():
         serial = serialize_for_storage(asdict_for_yaml_dump(data))
-        yaml_content = yaml.dump(serial, default_flow_style=False, sort_keys=True)
+        yaml_content = yaml.dump(
+            serial, default_flow_style=False, sort_keys=True, Dumper=yaml.CDumper
+        )
         util.rewrite_file(f"{output}/namespace_{namespace}.yaml", yaml_content)
 
 
@@ -451,6 +453,7 @@ def _build_map_type(
 
     if isinstance(stype, builder.SpecTypeDefnAlias):
         ext_info = _parse_ext_info(stype.ext_info)
+        alias_params = stype.parameters if len(stype.parameters) > 0 else None
         return MapTypeAlias(
             type_name=stype.name,
             label=stype.label,
@@ -458,6 +461,7 @@ def _build_map_type(
             alias_type_path=type_path_of(stype.alias),
             ext_info=_parse_ext_info(stype.ext_info),
             discriminator=stype.discriminator,
+            parameters=alias_params,
         )
 
     if isinstance(stype, builder.SpecTypeDefnUnion):

uncountable/core/environment.py

@@ -26,6 +26,10 @@ def get_local_admin_server_port() -> int:
     return int(os.environ.get("UNC_ADMIN_SERVER_PORT", "50051"))
 
 
+def get_integration_admin_token() -> str | None:
+    return os.environ.get("UNC_INTEGRATION_ADMIN_TOKEN")
+
+
 def get_otel_enabled() -> bool:
     return os.environ.get("UNC_OTEL_ENABLED") == "true"
 

uncountable/integration/http_server/types.py

@@ -28,6 +28,18 @@ class HttpException(Exception):
     def body_parse_error() -> "HttpException":
         return HttpException(error_code=400, message="body parse error")
 
+    @staticmethod
+    def unauthorized() -> "HttpException":
+        return HttpException(error_code=401, message="unauthorized")
+
+    @staticmethod
+    def service_unavailable() -> "HttpException":
+        return HttpException(error_code=503, message="service unavailable")
+
+    @staticmethod
+    def bad_gateway() -> "HttpException":
+        return HttpException(error_code=502, message="bad gateway")
+
     @staticmethod
     def unknown_error() -> "HttpException":
         return HttpException(error_code=500, message="internal server error")

uncountable/integration/queue_runner/job_scheduler.py

@@ -237,7 +237,7 @@ async def start_scheduler(
                     command_task.cancel()
                     result_task.cancel()
                     return
-                elif task == command_task:
+                if task == command_task:
                     command = command_task.result()
                     match command:
                         case CommandEnqueueJob():

uncountable/integration/webhook_server/admin_auth.py

@@ -0,0 +1,38 @@
+import functools
+import hmac
+from collections.abc import Callable
+
+import flask
+from flask.typing import ResponseReturnValue
+from uncountable.core.environment import get_integration_admin_token
+from uncountable.integration.http_server import HttpException
+
+_BEARER_PREFIX = "Bearer "
+
+
+def _extract_bearer_token(authorization_header: str | None) -> str | None:
+    if authorization_header is None:
+        return None
+    if not authorization_header.startswith(_BEARER_PREFIX):
+        return None
+    return authorization_header[len(_BEARER_PREFIX) :]
+
+
+def require_admin_auth(
+    view: Callable[..., ResponseReturnValue],
+) -> Callable[..., ResponseReturnValue]:
+    @functools.wraps(view)
+    def wrapper(*args: object, **kwargs: object) -> ResponseReturnValue:
+        admin_token = get_integration_admin_token()
+        if admin_token is None:
+            raise HttpException.service_unavailable()
+        provided_token = _extract_bearer_token(
+            flask.request.headers.get("Authorization")
+        )
+        if provided_token is None or not hmac.compare_digest(
+            provided_token, admin_token
+        ):
+            raise HttpException.unauthorized()
+        return view(*args, **kwargs)
+
+    return wrapper

uncountable/integration/webhook_server/admin_routes.py

@@ -0,0 +1,49 @@
+import flask
+from flask.typing import ResponseReturnValue
+from opentelemetry.trace import get_current_span
+from uncountable.core.environment import get_local_admin_server_port
+from uncountable.integration.http_server import HttpException
+from uncountable.integration.queue_runner.command_server.command_client import (
+    check_health,
+)
+from uncountable.integration.queue_runner.command_server.types import (
+    CommandServerException,
+)
+from uncountable.integration.telemetry import Logger
+from uncountable.integration.webhook_server.admin_auth import require_admin_auth
+
+_ADMIN_HEALTH_ROUTE = "/admin/health"
+
+
+def register_admin_routes(app: flask.Flask) -> None:
+    server_logger = Logger(get_current_span())
+
+    @require_admin_auth
+    def handle_admin_health() -> ResponseReturnValue:
+        healthy = check_health(port=get_local_admin_server_port())
+        return flask.jsonify({"healthy": healthy})
+
+    def admin_health() -> ResponseReturnValue:
+        with server_logger.push_scope(_ADMIN_HEALTH_ROUTE):
+            try:
+                return handle_admin_health()
+            except HttpException as e:
+                return e.make_error_response()
+            except CommandServerException as e:
+                server_logger.log_exception(
+                    e,
+                    message="admin health check could not reach the command server",
+                )
+                return HttpException.bad_gateway().make_error_response()
+            except Exception as e:
+                server_logger.log_exception(
+                    e, message=f"unexpected error on GET {_ADMIN_HEALTH_ROUTE}"
+                )
+                return HttpException.unknown_error().make_error_response()
+
+    app.add_url_rule(
+        _ADMIN_HEALTH_ROUTE,
+        endpoint="admin_health",
+        view_func=admin_health,
+        methods=["GET"],
+    )