@runuai/host 0.9.148 → 0.9.149

package/scripts/agent/env-hook.sh

@@ -0,0 +1,626 @@
+#!/bin/sh
+# Uai's task-local project environment loader (ADR-153).
+#
+# This file is sourced, never executed.  Keep the hot path shell-native for
+# bash and zsh: it runs before every task command.  dash and other POSIX
+# shells use curl because they have no TCP socket builtin.
+
+# HTTP is deliberately a tiny, closed protocol.  The trusted task forwarder
+# emits CRLF, a Content-Length on every 200, and a strong ETag containing
+# exactly 64 lowercase hex characters. These constants avoid a command
+# substitution (and therefore a fork) in bash/zsh.
+if [ -n "${BASH_VERSION-}" ] || [ -n "${ZSH_VERSION-}" ]; then
+  __uai_env_cr=$'\r'
+else
+  __uai_env_cr=$(printf '\r')
+fi
+__uai_env_nl='
+'
+
+# Keep this in lockstep with TASK_GATEWAY_MAX_ENV_BYTES. The native socket
+# readers still reject a short body before parsing or evaluating it.
+__uai_env_max_body_bytes=524288
+__uai_env_max_header_bytes=16384
+__uai_env_backoff_seconds=10
+
+__uai_env_now() {
+  if [ "${UAI_ENV_HOOK_TESTING-}" = "1" ] &&
+     [ -n "${UAI_ENV_TEST_NOW-}" ]; then
+    __uai_env_now_value=$UAI_ENV_TEST_NOW
+    return 0
+  fi
+  case ${SECONDS-} in
+    ''|*[!0-9]*)
+      __uai_env_now_value=$(date +%s 2>/dev/null) || __uai_env_now_value=0
+      ;;
+    *) __uai_env_now_value=$SECONDS ;;
+  esac
+}
+
+__uai_env_port() {
+  __uai_env_port_value=5877
+  if [ "${UAI_ENV_HOOK_TESTING-}" = "1" ]; then
+    case ${UAI_ENV_TEST_PORT-} in
+      ''|*[!0-9]*) return 1 ;;
+      *)
+        if [ "$UAI_ENV_TEST_PORT" -lt 1 ] ||
+           [ "$UAI_ENV_TEST_PORT" -gt 65535 ]; then
+          return 1
+        fi
+        __uai_env_port_value=$UAI_ENV_TEST_PORT
+        ;;
+    esac
+  fi
+}
+
+__uai_env_valid_revision() {
+  [ "${#1}" -eq 64 ] || return 1
+  case $1 in
+    *[!0-9a-f]*) return 1 ;;
+  esac
+  return 0
+}
+
+__uai_env_valid_name() {
+  case $1 in
+    ''|[!A-Za-z_]*|*[!A-Za-z0-9_]*|__UAI_ENV_*) return 1 ;;
+  esac
+  return 0
+}
+
+# A loader container starts with every project-owned name explicitly empty so
+# Compose overrides any ENV baked into a derived image.  A fresh shell has no
+# __UAI_ENV_KEYS yet, so the first response also needs the complete launch-time
+# name set in order to distinguish an absent key from an intentionally empty
+# value.  The runner mounts this list read-only; read and validate it once with
+# shell builtins so Bash/Zsh's per-command hot path never forks.
+__uai_env_load_managed_keys() {
+  local __uai_file=/run/uai/managed-env-keys
+  local __uai_line __uai_keys= __uai_seen=' '
+
+  [ "${__uai_env_managed_keys_loaded-0}" != "1" ] || return 0
+  if [ "${UAI_ENV_HOOK_TESTING-}" = "1" ] &&
+     [ -n "${UAI_ENV_TEST_MANAGED_KEYS-}" ]; then
+    __uai_file=$UAI_ENV_TEST_MANAGED_KEYS
+  fi
+
+  # Direct machine tasks have no image environment to clear and therefore do
+  # not need this container-only metadata file.
+  [ ! -L "$__uai_file" ] || return 1
+  if [ ! -e "$__uai_file" ]; then
+    __uai_env_managed_keys=
+    __uai_env_managed_keys_loaded=1
+    return 0
+  fi
+  [ -f "$__uai_file" ] || return 1
+
+  while IFS= read -r __uai_line || [ -n "$__uai_line" ]; do
+    __uai_env_valid_name "$__uai_line" || return 1
+    case $__uai_seen in
+      *" $__uai_line "*) return 1 ;;
+    esac
+    __uai_seen="${__uai_seen}${__uai_line} "
+    if [ -n "$__uai_keys" ]; then
+      __uai_keys="$__uai_keys $__uai_line"
+    else
+      __uai_keys=$__uai_line
+    fi
+  done < "$__uai_file"
+
+  __uai_env_managed_keys=$__uai_keys
+  __uai_env_managed_keys_loaded=1
+  return 0
+}
+
+__uai_env_trim_header_value() {
+  __uai_env_trimmed=$1
+  while [ "${__uai_env_trimmed# }" != "$__uai_env_trimmed" ]; do
+    __uai_env_trimmed=${__uai_env_trimmed# }
+  done
+  while [ "${__uai_env_trimmed% }" != "$__uai_env_trimmed" ]; do
+    __uai_env_trimmed=${__uai_env_trimmed% }
+  done
+}
+
+# Parse a complete header block (status line first, no terminating blank line).
+# On success it sets __uai_env_http_status, __uai_env_http_length and
+# __uai_env_http_etag.  The endpoint is intentionally stricter than a general
+# HTTP client: transfer coding, duplicate framing, and non-canonical ETags are
+# all rejected before a byte is evaluated as shell input.
+__uai_env_parse_headers() {
+  local LC_ALL=C
+  local __uai_block=$1 __uai_line __uai_rest __uai_status __uai_name
+  local __uai_length= __uai_etag= __uai_seen_length=0 __uai_seen_etag=0
+
+  [ "${#__uai_block}" -le "$__uai_env_max_header_bytes" ] || return 1
+  __uai_status=${__uai_block%%"$__uai_env_nl"*}
+  __uai_status=${__uai_status%"$__uai_env_cr"}
+  if [ "$__uai_status" = "$__uai_block" ]; then
+    __uai_rest=
+  else
+    __uai_rest=${__uai_block#*"$__uai_env_nl"}
+  fi
+  case $__uai_status in
+    'HTTP/1.0 200 '*|'HTTP/1.1 200 '*) __uai_env_http_status=200 ;;
+    'HTTP/1.0 304 '*|'HTTP/1.1 304 '*) __uai_env_http_status=304 ;;
+    *) return 1 ;;
+  esac
+
+  while [ -n "$__uai_rest" ]; do
+    __uai_line=${__uai_rest%%"$__uai_env_nl"*}
+    if [ "$__uai_line" = "$__uai_rest" ]; then
+      __uai_rest=
+    else
+      __uai_rest=${__uai_rest#*"$__uai_env_nl"}
+    fi
+    __uai_line=${__uai_line%"$__uai_env_cr"}
+    [ -n "$__uai_line" ] || return 1
+    case $__uai_line in
+      [Cc][Oo][Nn][Tt][Ee][Nn][Tt]-[Ll][Ee][Nn][Gg][Tt][Hh]:*)
+        [ "$__uai_seen_length" -eq 0 ] || return 1
+        __uai_seen_length=1
+        __uai_env_trim_header_value "${__uai_line#*:}"
+        __uai_length=$__uai_env_trimmed
+        case $__uai_length in
+          0|[1-9]|[1-9][0-9]*) ;;
+          *) return 1 ;;
+        esac
+        ;;
+      [Ee][Tt][Aa][Gg]:*)
+        [ "$__uai_seen_etag" -eq 0 ] || return 1
+        __uai_seen_etag=1
+        __uai_env_trim_header_value "${__uai_line#*:}"
+        case $__uai_env_trimmed in
+          \"*\")
+            __uai_etag=${__uai_env_trimmed#\"}
+            __uai_etag=${__uai_etag%\"}
+            ;;
+          *) return 1 ;;
+        esac
+        __uai_env_valid_revision "$__uai_etag" || return 1
+        ;;
+      [Tt][Rr][Aa][Nn][Ss][Ff][Ee][Rr]-[Ee][Nn][Cc][Oo][Dd][Ii][Nn][Gg]:*)
+        return 1
+        ;;
+      *:*)
+        # Header values are opaque here. Validate only the field name: a
+        # normal Node response includes values such as
+        # `Date: Thu, 01 Oct 2026 00:23:00 GMT`.
+        __uai_name=${__uai_line%%:*}
+        case $__uai_name in
+          ''|*[!A-Za-z0-9_-]*) return 1 ;;
+        esac
+        ;;
+      *) return 1 ;;
+    esac
+  done
+
+  [ "$__uai_seen_etag" -eq 1 ] || return 1
+  if [ "$__uai_env_http_status" -eq 304 ]; then
+    # A 304 has no message body and Node's HTTP server correctly omits
+    # Content-Length. Accept an explicit zero, but no other framing.
+    if [ "$__uai_seen_length" -eq 1 ]; then
+      [ "$__uai_length" -eq 0 ] || return 1
+    else
+      __uai_length=0
+    fi
+    [ -n "${__UAI_ENV_ETAG-}" ] || return 1
+    [ "$__uai_etag" = "$__UAI_ENV_ETAG" ] || return 1
+  else
+    [ "$__uai_seen_length" -eq 1 ] || return 1
+    [ "$__uai_length" -le "$__uai_env_max_body_bytes" ] || return 1
+    [ "$__uai_length" -gt 0 ] || return 1
+  fi
+  __uai_env_http_length=$__uai_length
+  __uai_env_http_etag=$__uai_etag
+  return 0
+}
+
+__uai_env_read_headers() {
+  local LC_ALL=C
+  local __uai_kind=$1 __uai_fd=$2 __uai_line __uai_block= __uai_count=0
+  while :; do
+    if ! IFS= read -r -t 2 -u "$__uai_fd" __uai_line; then
+      return 1
+    fi
+    __uai_line=${__uai_line%"$__uai_env_cr"}
+    __uai_count=$((__uai_count + ${#__uai_line} + 1))
+    [ "$__uai_count" -le "$__uai_env_max_header_bytes" ] || return 1
+    if [ -z "$__uai_line" ]; then
+      break
+    fi
+    if [ -z "$__uai_block" ]; then
+      __uai_block=$__uai_line
+    else
+      __uai_block="${__uai_block}${__uai_env_nl}${__uai_line}"
+    fi
+  done
+  [ -n "$__uai_block" ] || return 1
+  __uai_env_parse_headers "$__uai_block" || return 1
+
+  __uai_env_http_body=
+  [ "$__uai_env_http_length" -gt 0 ] || return 0
+  if [ "$__uai_kind" = "zsh" ]; then
+    # zsh's `read -k N -t` applies the timeout only while waiting for the
+    # first byte; a peer can send one byte and then stall the shell forever.
+    # sysread returns whatever is currently available, so loop under one
+    # wall-clock deadline for the complete body.
+    zmodload zsh/system 2>/dev/null || return 1
+    zmodload zsh/datetime 2>/dev/null || return 1
+    local -F __uai_deadline __uai_remaining
+    local -i __uai_needed
+    local __uai_chunk
+    __uai_deadline=$(( EPOCHREALTIME + 2.0 ))
+    while [ "${#__uai_env_http_body}" -lt "$__uai_env_http_length" ]; do
+      __uai_remaining=$(( __uai_deadline - EPOCHREALTIME ))
+      (( __uai_remaining > 0.0 )) || return 1
+      __uai_needed=$(( __uai_env_http_length - ${#__uai_env_http_body} ))
+      if ! sysread -t "$__uai_remaining" -i "$__uai_fd" \
+          -s "$__uai_needed" __uai_chunk; then
+        return 1
+      fi
+      [ -n "$__uai_chunk" ] || return 1
+      __uai_env_http_body="${__uai_env_http_body}${__uai_chunk}"
+    done
+  else
+    IFS= read -r -N "$__uai_env_http_length" -u "$__uai_fd" -t 2 \
+      __uai_env_http_body || return 1
+  fi
+  [ "${#__uai_env_http_body}" -eq "$__uai_env_http_length" ] || return 1
+  return 0
+}
+
+__uai_env_request_text() {
+  __uai_env_request="GET /env HTTP/1.0${__uai_env_cr}${__uai_env_nl}Host: 127.0.0.1${__uai_env_cr}${__uai_env_nl}Connection: close${__uai_env_cr}${__uai_env_nl}"
+  if [ -n "${__UAI_ENV_ETAG-}" ]; then
+    __uai_env_valid_revision "$__UAI_ENV_ETAG" || return 1
+    __uai_env_request="${__uai_env_request}If-None-Match: \"${__UAI_ENV_ETAG}\"${__uai_env_cr}${__uai_env_nl}"
+  fi
+  __uai_env_request="${__uai_env_request}${__uai_env_cr}${__uai_env_nl}"
+}
+
+__uai_env_http_bash() {
+  local __uai_fd __uai_rc=1
+  __uai_env_port || return 1
+  __uai_env_request_text || return 1
+  if ! eval 'exec {__uai_fd}<>"/dev/tcp/127.0.0.1/'"$__uai_env_port_value"'"' \
+      2>/dev/null; then
+    return 1
+  fi
+  if printf '%s' "$__uai_env_request" >&"$__uai_fd" 2>/dev/null &&
+     __uai_env_read_headers bash "$__uai_fd"; then
+    __uai_rc=0
+  fi
+  eval 'exec {__uai_fd}>&-' 2>/dev/null || :
+  return "$__uai_rc"
+}
+
+__uai_env_http_zsh() {
+  local __uai_fd __uai_rc=1
+  __uai_env_port || return 1
+  __uai_env_request_text || return 1
+  zmodload zsh/net/tcp 2>/dev/null || return 1
+  ztcp 127.0.0.1 "$__uai_env_port_value" 2>/dev/null || return 1
+  __uai_fd=$REPLY
+  if print -rn -u "$__uai_fd" -- "$__uai_env_request" 2>/dev/null &&
+     __uai_env_read_headers zsh "$__uai_fd"; then
+    __uai_rc=0
+  fi
+  ztcp -c "$__uai_fd" 2>/dev/null || :
+  return "$__uai_rc"
+}
+
+__uai_env_parse_curl_response() {
+  local LC_ALL=C
+  local __uai_raw=$1 __uai_separator __uai_headers
+  __uai_separator="${__uai_env_cr}${__uai_env_nl}${__uai_env_cr}${__uai_env_nl}"
+  case $__uai_raw in
+    *"$__uai_separator"*) ;;
+    *) return 1 ;;
+  esac
+  __uai_headers=${__uai_raw%%"$__uai_separator"*}
+  __uai_env_http_body=${__uai_raw#*"$__uai_separator"}
+  __uai_env_parse_headers "$__uai_headers" || return 1
+  [ "${#__uai_env_http_body}" -eq "$__uai_env_http_length" ] || return 1
+  return 0
+}
+
+__uai_env_http_curl() {
+  local __uai_raw __uai_marker='__UAI_ENV_CURL_CAPTURE_END__'
+  __uai_env_port || return 1
+  __uai_env_request_text || return 1
+  if [ -n "${__UAI_ENV_ETAG-}" ]; then
+    __uai_raw=$(
+      /usr/bin/curl --silent --http1.0 --include --raw --noproxy '*' \
+        --connect-timeout 1 --max-time 2 \
+        --header 'Connection: close' \
+        --header "If-None-Match: \"${__UAI_ENV_ETAG}\"" \
+        "http://127.0.0.1:${__uai_env_port_value}/env" 2>/dev/null &&
+      printf '%s' "$__uai_marker"
+    ) || return 1
+  else
+    __uai_raw=$(
+      /usr/bin/curl --silent --http1.0 --include --raw --noproxy '*' \
+        --connect-timeout 1 --max-time 2 \
+        --header 'Connection: close' \
+        "http://127.0.0.1:${__uai_env_port_value}/env" 2>/dev/null &&
+      printf '%s' "$__uai_marker"
+    ) || return 1
+  fi
+  case $__uai_raw in
+    *"$__uai_marker") __uai_raw=${__uai_raw%"$__uai_marker"} ;;
+    *) return 1 ;;
+  esac
+  __uai_env_parse_curl_response "$__uai_raw"
+}
+
+__uai_env_http() {
+  if [ -n "${ZSH_VERSION-}" ]; then
+    __uai_env_http_zsh
+  elif [ -n "${BASH_VERSION-}" ]; then
+    __uai_env_http_bash
+  else
+    __uai_env_http_curl
+  fi
+}
+
+__uai_env_parse_body() {
+  local LC_ALL=C
+  local __uai_body=$1 __uai_without_last_nl __uai_last __uai_head
+  local __uai_first __uai_keys __uai_script __uai_key __uai_seen=' '
+
+  case $__uai_body in
+    *"$__uai_env_nl") ;;
+    *) return 1 ;;
+  esac
+  __uai_without_last_nl=${__uai_body%"$__uai_env_nl"}
+  __uai_last=${__uai_without_last_nl##*"$__uai_env_nl"}
+  [ "$__uai_last" != "$__uai_without_last_nl" ] || return 1
+  [ "$__uai_last" = "# uai-env-v1 end=${__uai_env_http_etag}" ] || return 1
+  __uai_head=${__uai_without_last_nl%"$__uai_env_nl$__uai_last"}
+  __uai_first=${__uai_head%%"$__uai_env_nl"*}
+  case $__uai_first in
+    '# uai-env-v1 keys='*) __uai_keys=${__uai_first#'# uai-env-v1 keys='} ;;
+    *) return 1 ;;
+  esac
+  case $__uai_keys in
+    *[!A-Za-z0-9_' ']*) return 1 ;;
+  esac
+  if [ "$__uai_head" = "$__uai_first" ]; then
+    __uai_script=
+  else
+    __uai_script=${__uai_head#*"$__uai_env_nl"}
+  fi
+
+  if [ -n "${ZSH_VERSION-}" ]; then
+    setopt localoptions shwordsplit
+  fi
+  for __uai_key in $__uai_keys; do
+    __uai_env_valid_name "$__uai_key" || return 1
+    case $__uai_seen in
+      *" $__uai_key "*) return 1 ;;
+    esac
+    __uai_seen="${__uai_seen}${__uai_key} "
+  done
+  __uai_env_validate_script "$__uai_script" "$__uai_keys" || return 1
+  __uai_env_body_keys=$__uai_keys
+  __uai_env_body_script=$__uai_script
+  return 0
+}
+
+# Accept only the renderer's exact grammar. Values may contain newlines and
+# any byte except NUL; an apostrophe is represented by the canonical POSIX
+# sequence '\'' (close quote, escaped quote, reopen quote). This scan is all
+# shell builtins, so a changed response still does not fork before eval.
+__uai_env_validate_script() {
+  local LC_ALL=C
+  local __uai_rest=$1 __uai_keys=$2 __uai_key __uai_prefix
+  local __uai_chunk __uai_tail __uai_consumed
+  if [ -n "${ZSH_VERSION-}" ]; then
+    setopt localoptions shwordsplit
+  fi
+  for __uai_key in $__uai_keys; do
+    __uai_prefix="export ${__uai_key}='"
+    case $__uai_rest in
+      "$__uai_prefix"*) __uai_rest=${__uai_rest#"$__uai_prefix"} ;;
+      *) return 1 ;;
+    esac
+    while :; do
+      # Scan toward the next quote in bounded chunks. Removing one byte at a
+      # time made a valid 100 KB refresh take tens of seconds because every
+      # removal copied the entire remaining suffix.
+      if [ -n "${BASH_VERSION-}${ZSH_VERSION-}" ]; then
+        # Bash and zsh's glob removal becomes superlinear on a long suffix.
+        # Bound each glob to 1 KiB, then advance by substring offset.
+        __uai_chunk=${__uai_rest:0:1024}
+        case $__uai_chunk in
+          *"'"*)
+            __uai_tail=${__uai_chunk#*"'"}
+            __uai_consumed=$(( ${#__uai_chunk} - ${#__uai_tail} ))
+            __uai_rest=${__uai_rest:$__uai_consumed}
+            ;;
+          *)
+            [ "${#__uai_chunk}" -eq 1024 ] || return 1
+            __uai_rest=${__uai_rest:1024}
+            continue
+            ;;
+        esac
+      else
+        case $__uai_rest in
+          *"'"*) __uai_rest=${__uai_rest#*"'"} ;;
+          *) return 1 ;;
+        esac
+      fi
+      case $__uai_rest in
+        "\\''"*) __uai_rest=${__uai_rest#"\\''"} ;;
+        '') break ;;
+        "$__uai_env_nl"*)
+          __uai_rest=${__uai_rest#"$__uai_env_nl"}
+          break
+          ;;
+        *) return 1 ;;
+      esac
+    done
+  done
+  [ -z "$__uai_rest" ]
+}
+
+__uai_env_apply() {
+  local __uai_old_keys __uai_key
+  if [ -n "${ZSH_VERSION-}" ]; then
+    setopt localoptions shwordsplit
+  fi
+  __uai_env_load_managed_keys || return 1
+  __uai_old_keys="${__UAI_ENV_KEYS-} ${__uai_env_managed_keys-}"
+  if ! eval "$__uai_env_body_script"; then
+    return 1
+  fi
+  for __uai_key in $__uai_old_keys; do
+    __uai_env_valid_name "$__uai_key" || continue
+    case " $__uai_env_body_keys " in
+      *" $__uai_key "*) ;;
+      *) unset "$__uai_key" ;;
+    esac
+  done
+  __UAI_ENV_KEYS=$__uai_env_body_keys
+  __UAI_ENV_ETAG=$__uai_env_http_etag
+  export __UAI_ENV_KEYS __UAI_ENV_ETAG
+  return 0
+}
+
+__uai_env_sync_inner() {
+  __uai_env_http || return 1
+  if [ "$__uai_env_http_status" -eq 304 ]; then
+    return 0
+  fi
+  __uai_env_parse_body "$__uai_env_http_body" || return 1
+  __uai_env_apply
+}
+
+__uai_env_sync() {
+  local __uai_now
+  if [ -n "${ZSH_VERSION-}" ]; then
+    emulate -L zsh
+  fi
+  [ "${UAI_ENV_HOOK-0}" = "1" ] || return 0
+  [ "${__uai_env_sync_active-0}" != "1" ] || return 0
+
+  __uai_env_now
+  __uai_now=$__uai_env_now_value
+  __uai_env_retry_after=${__uai_env_retry_after-0}
+  case ${__uai_env_retry_after-0} in
+    ''|*[!0-9]*) __uai_env_retry_after=0 ;;
+  esac
+  if [ "$__uai_now" -lt "$__uai_env_retry_after" ]; then
+    return 0
+  fi
+
+  __uai_env_sync_active=1
+  if __uai_env_sync_inner; then
+    __uai_env_retry_after=0
+    __uai_env_warned=0
+  else
+    __uai_env_retry_after=$((__uai_now + __uai_env_backoff_seconds))
+    if [ -z "${__UAI_ENV_ETAG-}" ] && [ "${__uai_env_warned-0}" != "1" ]; then
+      printf '%s\n' \
+        'uai: project environment is temporarily unavailable; retrying' >&2
+      __uai_env_warned=1
+    fi
+  fi
+  __uai_env_sync_active=0
+  return 0
+}
+
+# Interactive zsh calls this through add-zsh-hook.  Keeping the callback in
+# the asset makes the task-up stub a one-line, idempotent registration.
+__uai_env_zsh_preexec() {
+  emulate -L zsh
+  # An interrupt unwinds the prior preexec before __uai_env_sync reaches its
+  # final assignment. At the next submitted command there cannot still be a
+  # live preexec, so clear that stale guard before trying again.
+  __uai_env_sync_active=0
+  __uai_env_sync
+}
+
+__uai_env_install_zsh_preexec() {
+  [ -n "${ZSH_VERSION-}" ] || return 0
+  emulate -L zsh
+  case $- in *i*) ;; *) return 0 ;; esac
+  [ "${__uai_env_zsh_preexec_installed-0}" != "1" ] || return 0
+  autoload -Uz add-zsh-hook || return 0
+  add-zsh-hook -d preexec __uai_env_zsh_preexec 2>/dev/null || :
+  add-zsh-hook preexec __uai_env_zsh_preexec
+  __uai_env_zsh_preexec_installed=1
+}
+
+# Interactive bash has no native preexec hook.  A DEBUG trap marks the first
+# simple command in a submitted command line; PROMPT_COMMAND clears the mark
+# only when the next prompt is drawn.  Existing DEBUG/PROMPT_COMMAND handlers
+# remain in the chain, including VS Code's shell integration.
+__uai_env_bash_preexec() {
+  __uai_env_sync
+}
+
+__uai_env_bash_precmd() {
+  # PROMPT_COMMAND runs after an interrupted preexec too. Clear both guards
+  # so the next submitted command retries instead of remaining disabled.
+  __uai_env_sync_active=0
+  __uai_env_bash_command_active=0
+}
+
+__uai_env_bash_debug_dispatch() {
+  local __uai_status=${1-0}
+  __uai_env_bash_restored_underscore=${2-}
+  if [ "${__uai_env_bash_command_active-0}" = "0" ]; then
+    __uai_env_bash_command_active=1
+    __uai_env_bash_preexec
+  fi
+  if [ -n "${__uai_env_bash_previous_debug-}" ]; then
+    builtin eval "$__uai_env_bash_previous_debug"
+  fi
+  return "$__uai_status"
+}
+
+__uai_env_bash_get_debug_trap() {
+  local -a __uai_terms
+  builtin eval "__uai_terms=( $(trap -p DEBUG) )"
+  builtin printf '%s' "${__uai_terms[2]-}"
+}
+
+__uai_env_install_bash_preexec() {
+  local __uai_prompt_decl
+  [ -n "${BASH_VERSION-}" ] || return 0
+  case $- in *i*) ;; *) return 0 ;; esac
+  [ "${__uai_env_bash_preexec_installed-0}" != "1" ] || return 0
+
+  __uai_env_bash_previous_debug=$(__uai_env_bash_get_debug_trap)
+  __uai_env_bash_command_active=1
+  # A DEBUG handler's own commands normally replace Bash's `$_`. Capture it
+  # as an argument before the dispatcher runs, then make it the trap's final
+  # argument so the submitted command observes the same previous argument.
+  trap '__uai_env_bash_debug_dispatch "$?" "$_"; : "$__uai_env_bash_restored_underscore"' DEBUG
+
+  __uai_prompt_decl=$(declare -p PROMPT_COMMAND 2>/dev/null || :)
+  case $__uai_prompt_decl in
+    'declare -a '*) builtin eval 'PROMPT_COMMAND+=(__uai_env_bash_precmd)' ;;
+    *)
+      if [ -n "${PROMPT_COMMAND-}" ]; then
+        PROMPT_COMMAND="${PROMPT_COMMAND};__uai_env_bash_precmd"
+      else
+        PROMPT_COMMAND=__uai_env_bash_precmd
+      fi
+      ;;
+  esac
+  __uai_env_bash_preexec_installed=1
+}
+
+# BASH_ENV points straight at this asset.  Bash also reads BASH_ENV for shell
+# scripts; those inherit the caller's already-refreshed environment and must
+# not pay another request.  Only `bash -c` has BASH_EXECUTION_STRING.
+if [ "${UAI_ENV_HOOK-0}" = "1" ] &&
+   [ -n "${BASH_VERSION-}" ] &&
+   [ -n "${BASH_EXECUTION_STRING-}" ] &&
+   [ -n "${BASH_ENV-}" ] &&
+   [ "$BASH_ENV" = "${BASH_SOURCE[0]-}" ]; then
+  __uai_env_sync
+fi