add files

R/asa_api_helpers.R

@@ -318,6 +318,364 @@ asa_api_error_fields <- function(message, error_code = NULL, details = NULL) {
   payload
 }
 
+asa_api_error_status <- function(message) {
+  if (grepl("direct-provider mode|does not provide `run_direct_task`", message, ignore.case = TRUE)) {
+    return(501L)
+  }
+  if (grepl("invalid json|required|must be|non-empty|unauthorized|password", message, ignore.case = TRUE)) {
+    return(400L)
+  }
+  500L
+}
+
+asa_api_drop_nulls <- function(value) {
+  if (!is.list(value)) {
+    return(value)
+  }
+
+  value[!vapply(value, is.null, logical(1))]
+}
+
+asa_api_make_diagnostic_id <- function(prefix = "asaapi") {
+  sprintf(
+    "%s-%s-%06d",
+    asa_api_scalar_chr(prefix, default = "asaapi"),
+    format(Sys.time(), "%Y%m%dT%H%M%SZ", tz = "UTC"),
+    as.integer(stats::runif(1, min = 0, max = 999999))
+  )
+}
+
+asa_api_redact_text_excerpt <- function(text, max_chars = 120L) {
+  text <- asa_api_scalar_chr(text, default = "")
+  if (!nzchar(text)) {
+    return("")
+  }
+
+  text <- gsub("[[:cntrl:]]+", " ", text)
+  text <- gsub("[[:space:]]+", " ", text)
+  text <- trimws(text)
+  if (!nzchar(text)) {
+    return("")
+  }
+
+  max_chars <- asa_api_scalar_int(max_chars, default = 120L)
+  if (is.na(max_chars) || max_chars < 16L) {
+    max_chars <- 120L
+  }
+
+  if (nchar(text, type = "chars") > max_chars) {
+    paste0(substr(text, 1L, max_chars), "...")
+  } else {
+    text
+  }
+}
+
+asa_api_redact_call_text <- function(call_text, max_chars = 240L) {
+  call_text <- asa_api_scalar_chr(call_text, default = "")
+  if (!nzchar(call_text)) {
+    return("")
+  }
+
+  call_text <- gsub('"[^"]*"', '"<redacted>"', call_text)
+  call_text <- gsub("'[^']*'", "'<redacted>'", call_text)
+  asa_api_redact_text_excerpt(call_text, max_chars = max_chars)
+}
+
+asa_api_prompt_summary <- function(prompt) {
+  prompt <- asa_api_scalar_chr(prompt, default = "")
+
+  list(
+    chars = nchar(prompt, type = "chars"),
+    excerpt = asa_api_redact_text_excerpt(prompt)
+  )
+}
+
+asa_api_prompts_summary <- function(prompts) {
+  prompts <- prompts %||% character(0)
+  prompts <- as.character(prompts)
+  prompt_lengths <- nchar(prompts, type = "chars")
+  prompt_lengths[is.na(prompt_lengths)] <- 0L
+
+  list(
+    count = length(prompts),
+    total_chars = sum(prompt_lengths),
+    max_chars = if (length(prompt_lengths)) max(prompt_lengths) else 0L,
+    first_prompt = if (length(prompts)) asa_api_prompt_summary(prompts[[1]]) else NULL
+  )
+}
+
+asa_api_runtime_config_summary <- function(config) {
+  if (!is.list(config) || !length(config)) {
+    return(list())
+  }
+
+  asa_api_drop_nulls(list(
+    backend = asa_api_scalar_chr(config$backend, default = ""),
+    model = asa_api_scalar_chr(config$model, default = ""),
+    conda_env = asa_api_scalar_chr(config$conda_env, default = ""),
+    use_browser = if (!is.null(config$use_browser)) isTRUE(config$use_browser) else NULL,
+    timeout = asa_api_scalar_int(config$timeout, default = NA_integer_),
+    rate_limit = asa_api_scalar_num(config$rate_limit, default = NA_real_),
+    workers = asa_api_scalar_int(config$workers, default = NA_integer_),
+    memory_folding = if (!is.null(config$memory_folding)) isTRUE(config$memory_folding) else NULL,
+    recursion_limit = asa_api_scalar_int(config$recursion_limit, default = NA_integer_)
+  ))
+}
+
+asa_api_runtime_defaults_summary <- function() {
+  asa_api_drop_nulls(list(
+    backend = getOption("asa.default_backend", NULL),
+    model = getOption("asa.default_model", NULL),
+    conda_env = getOption("asa.default_conda_env", "asa_env"),
+    use_browser = asa_api_to_bool(Sys.getenv("ASA_USE_BROWSER_DEFAULT", unset = "false"), default = FALSE)
+  ))
+}
+
+asa_api_runtime_tor_summary <- function() {
+  tor <- asa_api_tor_health()
+
+  asa_api_drop_nulls(list(
+    tor_enabled = isTRUE(tor$tor_enabled),
+    tor_ready = isTRUE(tor$tor_ready),
+    tor_proxy_host = tor$tor_proxy_host %||% NULL,
+    tor_proxy_port = tor$tor_proxy_port %||% NULL,
+    tor_proxy_port_open = isTRUE(tor$tor_proxy_port_open),
+    tor_control_port = tor$tor_control_port %||% NULL,
+    tor_control_port_open = isTRUE(tor$tor_control_port_open),
+    tor_cookie_present = isTRUE(tor$tor_cookie_present),
+    tor_cookie_readable = isTRUE(tor$tor_cookie_readable)
+  ))
+}
+
+asa_api_runtime_error_summary <- function(error) {
+  if (is.null(error)) {
+    return(list())
+  }
+
+  err_call <- conditionCall(error)
+  call_text <- if (is.null(err_call)) "" else paste(deparse(err_call, width.cutoff = 120L), collapse = " ")
+
+  asa_api_drop_nulls(list(
+    message = conditionMessage(error),
+    class = as.character(class(error)),
+    call = if (nzchar(call_text)) asa_api_redact_call_text(call_text) else NULL
+  ))
+}
+
+asa_api_runtime_stage <- function(stage_ref, default = "invoke") {
+  if (is.environment(stage_ref)) {
+    return(asa_api_scalar_chr(stage_ref$value, default = default))
+  }
+
+  asa_api_scalar_chr(stage_ref, default = default)
+}
+
+asa_api_build_runtime_diagnostic <- function(mode,
+                                             route,
+                                             payload = NULL,
+                                             prompt = NULL,
+                                             prompts = NULL,
+                                             config = NULL,
+                                             forwarded_arg_names = character(0),
+                                             request_shape = list(),
+                                             stage = "invoke",
+                                             error = NULL,
+                                             diagnostic_id = asa_api_make_diagnostic_id()) {
+  request_shape <- asa_api_named_list(request_shape)
+  request_shape$include_raw_output <- asa_api_to_bool(payload$include_raw_output, default = FALSE)
+  request_shape$include_trace_json <- asa_api_to_bool(payload$include_trace_json, default = FALSE)
+  if (!is.null(payload$use_direct_provider)) {
+    request_shape$use_direct_provider <- asa_api_to_bool(payload$use_direct_provider, default = FALSE)
+  }
+  request_shape$forwarded_arg_names <- sort(unique(as.character(forwarded_arg_names)))
+
+  if (!is.null(prompt)) {
+    request_shape$prompt <- asa_api_prompt_summary(prompt)
+  }
+  if (!is.null(prompts)) {
+    request_shape$prompts <- asa_api_prompts_summary(prompts)
+  }
+
+  asa_api_drop_nulls(list(
+    diagnostic_id = asa_api_scalar_chr(diagnostic_id, default = asa_api_make_diagnostic_id()),
+    timestamp_utc = format(Sys.time(), "%Y-%m-%dT%H:%M:%SZ", tz = "UTC"),
+    mode = asa_api_scalar_chr(mode, default = "unknown"),
+    route = asa_api_scalar_chr(route, default = "unknown"),
+    stage = asa_api_scalar_chr(stage, default = "invoke"),
+    request = asa_api_drop_nulls(request_shape),
+    config = asa_api_runtime_config_summary(config),
+    runtime = list(
+      asa_version = tryCatch(as.character(utils::packageVersion("asa")), error = function(e) NA_character_),
+      defaults = asa_api_runtime_defaults_summary(),
+      direct_provider_available = tryCatch(isTRUE(asa_api_has_run_direct_task()), error = function(e) FALSE),
+      tor = asa_api_runtime_tor_summary()
+    ),
+    error = asa_api_runtime_error_summary(error)
+  ))
+}
+
+asa_api_emit_runtime_diagnostic <- function(diagnostic, log_con = stderr()) {
+  if (requireNamespace("reticulate", quietly = TRUE)) {
+    diagnostic <- tryCatch(reticulate::py_to_r(diagnostic), error = function(e) diagnostic)
+  }
+  diagnostic <- asa_api_named_list(diagnostic)
+  diagnostic_id <- asa_api_scalar_chr(diagnostic$diagnostic_id, default = "unknown")
+  mode <- asa_api_scalar_chr(diagnostic$mode, default = "unknown")
+  route <- asa_api_scalar_chr(diagnostic$route, default = "unknown")
+  stage <- asa_api_scalar_chr(diagnostic$stage, default = "invoke")
+  error_message <- asa_api_scalar_chr((diagnostic$error %||% list())$message, default = "Request failed.")
+
+  cat(
+    sprintf(
+      "[asa-api] runtime failure diagnostic_id=%s mode=%s route=%s stage=%s error=%s\n",
+      diagnostic_id,
+      mode,
+      route,
+      stage,
+      error_message
+    ),
+    file = log_con
+  )
+
+  diagnostic_json <- tryCatch(
+    jsonlite::toJSON(diagnostic, auto_unbox = TRUE, null = "null", force = TRUE, digits = NA),
+    error = function(e) {
+      jsonlite::toJSON(
+        list(
+          diagnostic_id = diagnostic_id,
+          serialization_error = conditionMessage(e)
+        ),
+        auto_unbox = TRUE,
+        null = "null",
+        force = TRUE
+      )
+    }
+  )
+  cat(
+    sprintf("[asa-api][diagnostic] %s\n", paste(diagnostic_json, collapse = "")),
+    file = log_con
+  )
+
+  invisible(diagnostic)
+}
+
+asa_api_runtime_error_code <- function(mode) {
+  mode <- asa_api_scalar_chr(mode, default = "")
+  if (identical(mode, "asa_agent_batch")) {
+    return("agent_batch_failure")
+  }
+  if (identical(mode, "provider_direct_single")) {
+    return("direct_provider_failure")
+  }
+  "agent_pipeline_failure"
+}
+
+asa_api_raise_runtime_failure <- function(error,
+                                          diagnostic,
+                                          mode,
+                                          status_code = 500L,
+                                          log_con = stderr()) {
+  diagnostic <- asa_api_emit_runtime_diagnostic(diagnostic, log_con = log_con)
+  diagnostic_id <- asa_api_scalar_chr(diagnostic$diagnostic_id, default = "unknown")
+  message <- sprintf("%s [diagnostic_id=%s]", conditionMessage(error), diagnostic_id)
+
+  condition <- simpleError(message)
+  condition$error_code <- asa_api_runtime_error_code(mode)
+  condition$details <- asa_api_drop_nulls(list(
+    diagnostic_id = diagnostic_id,
+    mode = diagnostic$mode %||% NULL,
+    route = diagnostic$route %||% NULL,
+    stage = diagnostic$stage %||% NULL,
+    request = diagnostic$request %||% NULL,
+    config = diagnostic$config %||% NULL,
+    runtime = diagnostic$runtime %||% NULL,
+    error = diagnostic$error %||% NULL
+  ))
+  condition$status_code <- asa_api_scalar_int(status_code, default = 500L)
+  class(condition) <- c("asa_api_runtime_error", class(condition))
+
+  stop(condition)
+}
+
+asa_api_invoke_with_runtime_diagnostics <- function(fn,
+                                                    mode,
+                                                    route,
+                                                    payload = NULL,
+                                                    prompt = NULL,
+                                                    prompts = NULL,
+                                                    config = NULL,
+                                                    forwarded_arg_names = character(0),
+                                                    request_shape = list(),
+                                                    stage_ref = NULL,
+                                                    status_code = 500L,
+                                                    log_con = stderr()) {
+  tryCatch(
+    fn(),
+    error = function(e) {
+      diagnostic <- asa_api_build_runtime_diagnostic(
+        mode = mode,
+        route = route,
+        payload = payload,
+        prompt = prompt,
+        prompts = prompts,
+        config = config,
+        forwarded_arg_names = forwarded_arg_names,
+        request_shape = request_shape,
+        stage = asa_api_runtime_stage(stage_ref, default = "invoke"),
+        error = e
+      )
+      asa_api_raise_runtime_failure(
+        error = e,
+        diagnostic = diagnostic,
+        mode = mode,
+        status_code = status_code,
+        log_con = log_con
+      )
+    }
+  )
+}
+
+asa_api_error_failure <- function(error) {
+  message <- conditionMessage(error)
+  failure <- list(
+    status_code = asa_api_error_status(message),
+    message = message
+  )
+
+  code <- asa_api_scalar_chr(error$error_code %||% "", default = "")
+  if (nzchar(code)) {
+    failure$error_code <- code
+  }
+
+  details <- error$details %||% NULL
+  if (requireNamespace("reticulate", quietly = TRUE)) {
+    details <- tryCatch(reticulate::py_to_r(details), error = function(e) details)
+  }
+  if (!is.null(details) && !is.list(details)) {
+    details <- asa_api_to_plain(details)
+  }
+  if (is.list(details) && length(details)) {
+    failure$details <- details
+  }
+
+  explicit_status <- asa_api_scalar_int(error$status_code %||% NA_integer_, default = NA_integer_)
+  if (!is.na(explicit_status)) {
+    failure$status_code <- explicit_status
+  }
+
+  failure
+}
+
+asa_api_request_context_route <- function(request_context, default) {
+  context <- asa_api_named_list(request_context)
+  asa_api_scalar_chr(context$route, default = default)
+}
+
+asa_api_request_context_log_con <- function(request_context) {
+  context <- asa_api_named_list(request_context)
+  context$log_con %||% stderr()
+}
+
 asa_api_missing_auth_env_vars <- function() {
   required <- c("ASA_API_BEARER_TOKEN", "GUI_PASSWORD")
   required[!nzchar(vapply(required, asa_api_secret_env_value, character(1)))]
@@ -760,93 +1118,196 @@ asa_api_is_result_like <- function(value) {
     (is.list(value) && !is.null(value$status) && !is.null(value$message))
 }
 
-asa_api_run_single_via_asa <- function(payload) {
+asa_api_run_single_via_asa <- function(payload, request_context = NULL) {
   asa_api_apply_env_defaults()
   prompt <- asa_api_require_prompt(payload)
   config <- asa_api_build_config(payload)
   run_args <- asa_api_build_run_args(payload)
+  route <- asa_api_request_context_route(request_context, "/v1/run")
+  log_con <- asa_api_request_context_log_con(request_context)
+  stage_ref <- new.env(parent = emptyenv())
+  stage_ref$value <- "invoke"
+  request_shape <- asa_api_drop_nulls(list(
+    output_format = asa_api_scalar_chr(run_args$output_format, default = "text"),
+    performance_profile = asa_api_scalar_chr(run_args$performance_profile, default = ""),
+    use_plan_mode = if (!is.null(run_args$use_plan_mode)) isTRUE(run_args$use_plan_mode) else NULL
+  ))
 
   args <- c(list(prompt = prompt, config = config), run_args)
   args <- asa_api_filter_formals(asa::run_task, args)
 
-  result <- do.call(asa::run_task, args)
+  result <- asa_api_invoke_with_runtime_diagnostics(
+    fn = function() do.call(asa::run_task, args),
+    mode = "asa_agent_single",
+    route = route,
+    payload = payload,
+    prompt = prompt,
+    config = config,
+    forwarded_arg_names = names(run_args),
+    request_shape = request_shape,
+    stage_ref = stage_ref,
+    log_con = log_con
+  )
   include_raw_output <- asa_api_to_bool(payload$include_raw_output, default = FALSE)
   include_trace_json <- asa_api_to_bool(payload$include_trace_json, default = FALSE)
-
-  asa_api_normalize_result(
-    result,
-    include_raw_output = include_raw_output,
-    include_trace_json = include_trace_json
+  stage_ref$value <- "normalize_result"
+
+  asa_api_invoke_with_runtime_diagnostics(
+    fn = function() {
+      asa_api_normalize_result(
+        result,
+        include_raw_output = include_raw_output,
+        include_trace_json = include_trace_json
+      )
+    },
+    mode = "asa_agent_single",
+    route = route,
+    payload = payload,
+    prompt = prompt,
+    config = config,
+    forwarded_arg_names = names(run_args),
+    request_shape = request_shape,
+    stage_ref = stage_ref,
+    log_con = log_con
   )
 }
 
-asa_api_run_single_via_direct <- function(payload) {
+asa_api_run_single_via_direct <- function(payload, request_context = NULL) {
   asa_api_apply_env_defaults()
   run_direct_task_fun <- asa_api_get_run_direct_task()
   prompt <- asa_api_require_prompt(payload)
   config <- asa_api_build_config(payload)
   direct_args <- asa_api_build_direct_args(payload, run_direct_task_fun = run_direct_task_fun)
+  route <- asa_api_request_context_route(request_context, "/gui/query")
+  log_con <- asa_api_request_context_log_con(request_context)
+  stage_ref <- new.env(parent = emptyenv())
+  stage_ref$value <- "invoke"
+  request_shape <- asa_api_drop_nulls(list(
+    output_format = asa_api_scalar_chr(direct_args$output_format, default = "text"),
+    performance_profile = asa_api_scalar_chr(direct_args$performance_profile, default = ""),
+    use_plan_mode = if (!is.null(direct_args$use_plan_mode)) isTRUE(direct_args$use_plan_mode) else NULL
+  ))
 
   args <- c(list(prompt = prompt, config = config), direct_args)
   args <- asa_api_filter_formals(run_direct_task_fun, args)
 
-  result <- do.call(run_direct_task_fun, args)
+  result <- asa_api_invoke_with_runtime_diagnostics(
+    fn = function() do.call(run_direct_task_fun, args),
+    mode = "provider_direct_single",
+    route = route,
+    payload = payload,
+    prompt = prompt,
+    config = config,
+    forwarded_arg_names = names(direct_args),
+    request_shape = request_shape,
+    stage_ref = stage_ref,
+    log_con = log_con
+  )
   include_raw_output <- asa_api_to_bool(payload$include_raw_output, default = FALSE)
   include_trace_json <- asa_api_to_bool(payload$include_trace_json, default = FALSE)
-
-  asa_api_normalize_result(
-    result,
-    include_raw_output = include_raw_output,
-    include_trace_json = include_trace_json
+  stage_ref$value <- "normalize_result"
+
+  asa_api_invoke_with_runtime_diagnostics(
+    fn = function() {
+      asa_api_normalize_result(
+        result,
+        include_raw_output = include_raw_output,
+        include_trace_json = include_trace_json
+      )
+    },
+    mode = "provider_direct_single",
+    route = route,
+    payload = payload,
+    prompt = prompt,
+    config = config,
+    forwarded_arg_names = names(direct_args),
+    request_shape = request_shape,
+    stage_ref = stage_ref,
+    log_con = log_con
   )
 }
 
-asa_api_run_single <- function(payload, allow_direct_provider = FALSE) {
+asa_api_run_single <- function(payload, allow_direct_provider = FALSE, request_context = NULL) {
   use_direct_provider <- isTRUE(allow_direct_provider) &&
     asa_api_to_bool(payload$use_direct_provider, default = FALSE)
 
   if (use_direct_provider) {
-    return(asa_api_run_single_via_direct(payload))
+    return(asa_api_run_single_via_direct(payload, request_context = request_context))
   }
 
-  asa_api_run_single_via_asa(payload)
+  asa_api_run_single_via_asa(payload, request_context = request_context)
 }
 
-asa_api_run_batch <- function(payload) {
+asa_api_run_batch <- function(payload, request_context = NULL) {
   asa_api_apply_env_defaults()
   prompts <- asa_api_require_prompts(payload)
   asa_api_validate_batch_supported_fields(payload)
   config <- asa_api_build_config(payload)
   batch_args <- asa_api_build_batch_args(payload)
+  route <- asa_api_request_context_route(request_context, "/v1/batch")
+  log_con <- asa_api_request_context_log_con(request_context)
+  stage_ref <- new.env(parent = emptyenv())
+  stage_ref$value <- "invoke"
+  request_shape <- asa_api_drop_nulls(list(
+    output_format = asa_api_scalar_chr(batch_args$output_format, default = "text"),
+    parallel = if (!is.null(batch_args$parallel)) isTRUE(batch_args$parallel) else NULL,
+    progress = if (!is.null(batch_args$progress)) isTRUE(batch_args$progress) else NULL,
+    performance_profile = asa_api_scalar_chr(batch_args$performance_profile, default = "")
+  ))
 
   args <- c(list(prompts = prompts, config = config), batch_args)
   args <- asa_api_filter_formals(asa::run_task_batch, args)
 
-  raw <- do.call(asa::run_task_batch, args)
+  raw <- asa_api_invoke_with_runtime_diagnostics(
+    fn = function() do.call(asa::run_task_batch, args),
+    mode = "asa_agent_batch",
+    route = route,
+    payload = payload,
+    prompts = prompts,
+    config = config,
+    forwarded_arg_names = names(batch_args),
+    request_shape = request_shape,
+    stage_ref = stage_ref,
+    log_con = log_con
+  )
   include_raw_output <- asa_api_to_bool(payload$include_raw_output, default = FALSE)
   include_trace_json <- asa_api_to_bool(payload$include_trace_json, default = FALSE)
+  stage_ref$value <- "normalize_batch_result"
+
+  asa_api_invoke_with_runtime_diagnostics(
+    fn = function() {
+      if (is.data.frame(raw) && "asa_result" %in% names(raw)) {
+        items <- lapply(raw$asa_result, asa_api_normalize_result,
+          include_raw_output = include_raw_output,
+          include_trace_json = include_trace_json
+        )
+      } else if (is.list(raw) && length(raw) && all(vapply(raw, asa_api_is_result_like, logical(1)))) {
+        items <- lapply(raw, asa_api_normalize_result,
+          include_raw_output = include_raw_output,
+          include_trace_json = include_trace_json
+        )
+      } else if (is.list(raw) && length(raw) == 0L) {
+        items <- list()
+      } else {
+        items <- list(asa_api_to_plain(raw))
+      }
 
-  if (is.data.frame(raw) && "asa_result" %in% names(raw)) {
-    items <- lapply(raw$asa_result, asa_api_normalize_result,
-      include_raw_output = include_raw_output,
-      include_trace_json = include_trace_json
-    )
-  } else if (is.list(raw) && length(raw) && all(vapply(raw, asa_api_is_result_like, logical(1)))) {
-    items <- lapply(raw, asa_api_normalize_result,
-      include_raw_output = include_raw_output,
-      include_trace_json = include_trace_json
-    )
-  } else if (is.list(raw) && length(raw) == 0L) {
-    items <- list()
-  } else {
-    items <- list(asa_api_to_plain(raw))
-  }
-
-  list(
-    status = "success",
-    results = items,
-    count = length(items),
-    circuit_breaker_aborted = isTRUE(attr(raw, "circuit_breaker_aborted"))
+      list(
+        status = "success",
+        results = items,
+        count = length(items),
+        circuit_breaker_aborted = isTRUE(attr(raw, "circuit_breaker_aborted"))
+      )
+    },
+    mode = "asa_agent_batch",
+    route = route,
+    payload = payload,
+    prompts = prompts,
+    config = config,
+    forwarded_arg_names = names(batch_args),
+    request_shape = request_shape,
+    stage_ref = stage_ref,
+    log_con = log_con
   )
 }
 

R/plumber.R

@@ -58,16 +58,6 @@ asa_api_failure_payload <- function(res, failure) {
   )
 }
 
-asa_api_error_status <- function(message) {
-  if (grepl("direct-provider mode|does not provide `run_direct_task`", message, ignore.case = TRUE)) {
-    return(501L)
-  }
-  if (grepl("invalid json|required|must be|non-empty|unauthorized|password", message, ignore.case = TRUE)) {
-    return(400L)
-  }
-  500L
-}
-
 #* @filter cors
 function(req, res) {
   allow_origin <- trimws(Sys.getenv("CORS_ALLOW_ORIGIN", unset = "*"))
@@ -142,10 +132,13 @@ function(req, res) {
   }
 
   tryCatch(
-    asa_api_run_single(payload, allow_direct_provider = FALSE),
+    asa_api_run_single(
+      payload,
+      allow_direct_provider = FALSE,
+      request_context = list(route = "/v1/run")
+    ),
     error = function(e) {
-      msg <- conditionMessage(e)
-      asa_api_error_payload(res, asa_api_error_status(msg), msg)
+      asa_api_failure_payload(res, asa_api_error_failure(e))
     }
   )
 }
@@ -172,10 +165,12 @@ function(req, res) {
   }
 
   tryCatch(
-    asa_api_run_batch(payload),
+    asa_api_run_batch(
+      payload,
+      request_context = list(route = "/v1/batch")
+    ),
     error = function(e) {
-      msg <- conditionMessage(e)
-      asa_api_error_payload(res, asa_api_error_status(msg), msg)
+      asa_api_failure_payload(res, asa_api_error_failure(e))
     }
   )
 }
@@ -211,11 +206,14 @@ function(req, res) {
 
   tryCatch(
     asa_api_sanitize_gui_result(
-      asa_api_run_single(payload, allow_direct_provider = TRUE)
+      asa_api_run_single(
+        payload,
+        allow_direct_provider = TRUE,
+        request_context = list(route = "/gui/query")
+      )
     ),
     error = function(e) {
-      msg <- conditionMessage(e)
-      asa_api_error_payload(res, asa_api_error_status(msg), msg)
+      asa_api_failure_payload(res, asa_api_error_failure(e))
     }
   )
 }

Tests/api_contract_smoke.R

@@ -322,6 +322,86 @@ assert_true(
   "Route error rendering should preserve structured auth diagnostics."
 )
 
+assert_true(
+  identical(asa_api_runtime_error_code("asa_agent_batch"), "agent_batch_failure") &&
+    identical(asa_api_runtime_error_code("provider_direct_single"), "direct_provider_failure") &&
+    identical(asa_api_runtime_error_code("asa_agent_single"), "agent_pipeline_failure"),
+  "Runtime failures should map to stable mode-specific error codes."
+)
+
+diagnostic_prompt <- paste(rep("diagnostic prompt segment", 16), collapse = " ")
+expected_excerpt <- asa_api_redact_text_excerpt(diagnostic_prompt)
+diagnostic_log_lines <- character(0)
+diagnostic_log_con <- textConnection("diagnostic_log_lines", "w", local = TRUE)
+runtime_error <- NULL
+tryCatch(
+  asa_api_invoke_with_runtime_diagnostics(
+    fn = function() {
+      stop("subscript out of bounds", call. = FALSE)
+    },
+    mode = "asa_agent_single",
+    route = "/v1/run",
+    payload = list(
+      include_raw_output = TRUE,
+      include_trace_json = FALSE
+    ),
+    prompt = diagnostic_prompt,
+    config = list(
+      backend = "gemini",
+      model = "gemini-2.5-pro",
+      conda_env = "asa_env",
+      use_browser = FALSE
+    ),
+    forwarded_arg_names = c("output_format", "performance_profile"),
+    request_shape = list(
+      output_format = "json",
+      performance_profile = "quality"
+    ),
+    stage_ref = "invoke",
+    log_con = diagnostic_log_con
+  ),
+  error = function(e) {
+    runtime_error <<- e
+    NULL
+  }
+)
+close(diagnostic_log_con)
+assert_true(
+  inherits(runtime_error, "asa_api_runtime_error") &&
+    identical(runtime_error$error_code, "agent_pipeline_failure"),
+  "Runtime diagnostics should rethrow a structured asa_api_runtime_error."
+)
+runtime_failure <- asa_api_error_failure(runtime_error)
+assert_true(
+  identical(runtime_failure$status_code, 500L) &&
+    identical(runtime_failure$error_code, "agent_pipeline_failure") &&
+    identical(runtime_failure$details$route, "/v1/run") &&
+    identical(runtime_failure$details$stage, "invoke") &&
+    identical(runtime_failure$details$request$output_format, "json") &&
+    identical(runtime_failure$details$request$include_raw_output, TRUE) &&
+    nzchar(runtime_failure$details$diagnostic_id),
+  "Structured runtime failures should preserve diagnostic metadata for API responses."
+)
+diagnostic_log_text <- paste(diagnostic_log_lines, collapse = "\n")
+assert_true(
+  grepl("diagnostic_id=", diagnostic_log_text, fixed = TRUE) &&
+    grepl("subscript out of bounds", diagnostic_log_text, fixed = TRUE),
+  "Runtime diagnostics should log the failure message with a correlation id."
+)
+assert_true(
+  grepl(expected_excerpt, diagnostic_log_text, fixed = TRUE) &&
+    !grepl(diagnostic_prompt, diagnostic_log_text, fixed = TRUE),
+  "Runtime diagnostics should log only a redacted prompt excerpt, not the full prompt."
+)
+runtime_res_env <- new.env(parent = emptyenv())
+runtime_payload <- asa_api_failure_payload(runtime_res_env, runtime_failure)
+assert_true(
+  identical(runtime_res_env$status, 500L) &&
+    identical(runtime_payload$error_code, "agent_pipeline_failure") &&
+    identical(runtime_payload$details$diagnostic_id, runtime_failure$details$diagnostic_id),
+  "Route error rendering should preserve structured runtime diagnostics."
+)
+
 health_payload <- asa_api_health_payload()
 assert_true(
   identical(isTRUE(health_payload$direct_provider_available), isTRUE(asa_api_has_run_direct_task())),
@@ -364,11 +444,11 @@ asa_api_refresh_auth_cache(force = TRUE)
   original_direct <- asa_api_run_single_via_direct
 
   dispatch_calls <- character(0)
-  asa_api_run_single_via_asa <- function(payload) {
+  asa_api_run_single_via_asa <- function(payload, request_context = NULL) {
     dispatch_calls <<- c(dispatch_calls, "asa")
     list(status = "success", execution = list(mode = "asa_agent"))
   }
-  asa_api_run_single_via_direct <- function(payload) {
+  asa_api_run_single_via_direct <- function(payload, request_context = NULL) {
     dispatch_calls <<- c(dispatch_calls, "direct")
     list(status = "success", execution = list(mode = "provider_direct"))
   }