Skip to content

[FEATURE] Consume typed upstream HTTP status from omnisdk and remove response-text munging #681

Open

Description

@jeffreyaven

Current scope

Priority: HIGH
Effort: HIGH

Consume the existing public omnisdk.HTTPStatusError contract in StackQL. The currently pinned omnisdk v0.1.11-beta1 already exposes StatusCode(), ResponseBody() and RequestURL() through errors.As.

This issue is not blocked on a future any-sdk release or a new SDK status-code feature. The HIGH effort rating is a planning override for the complete integration and regression work; it is not evidence of a missing SDK API. Recreate an omnisdk defect only if a concrete execution path is shown to lose the public error contract.

Acceptance

  • Replace HTTP-status regex classification in classifyBackendError with errors.As(err, &response) using omnisdk.HTTPStatusError.
  • Preserve wrapped typed errors through execution, streaming/pagination, staging and MCP response handling. Formatting diagnostics must not replace the programmatic error chain.
  • Preserve the established read-404 empty-result policy without suppressing authentication or mutation failures.
  • Preserve MCP http_status and retryable behavior: 408/429/5xx retryable; other 4xx not retryable under the existing contract.
  • Cover 403, 404, 408, 429 and 5xx; JSON, HTML, XML, plain-text and empty bodies; misleading body text; wrapped and late-page errors; and GraphQL HTTP failures. A 403 body mentioning "404" or "not found" must remain 403.
  • Transport failures without an HTTP response must not acquire an invented HTTP status. HTTP-200 GraphQL payload errors remain separate from HTTP-status classification.
  • Remove obsolete HTTP-status text fallbacks. Do not require deleted any-sdk execution classes or duplicate SDK functionality.
  • Keep the existing MCP 403/429/404 robot regressions and add focused host unit coverage.

Legacy origin

Supersedes the dependency on stackql/any-sdk#115. Its requested typed-error alternative is supplied by the pinned omnisdk API. StackQL #681 stays open until host integration and acceptance pass.

Original any-sdk design (historical)

Description

The issue #670 fix (MCP tools surface upstream HTTP errors instead of empty result sets, with 404 exempted as database-semantics "zero rows") currently recovers the upstream status by parsing any-sdk's error message text, because the status code is not carried through the any-sdk invoker boundary (providerinvoker.Result is just {Body, Messages}):

  • internal/stackql/execution (isUpstreamNotFound): the structured fragment regex (?i)status code:?\s*(\d{3}) is authoritative when present (a 403 whose body mentions "not found" is still an error); unstructured bodies (HTML / XML / plain text published verbatim) fall back to a loose, any-case match:
var upstreamNotFoundLooseRegex = regexp.MustCompile(`(?i)\b404\b|not\s+found`)
  • internal/stackql/mcpbackend (classifyBackendError): the same fragment regex classifies MCP tool errors as upstream http error: {"http_status": N, "retryable": bool} (408/429/5xx retryable).

This works for mainstream provider error shapes but is fragile by construction: the status is only present when any-sdk happens to format it into the text, and the loose fallback trades precision for safety (a false positive restores the historical empty-result behaviour, which is the safe direction).

Proposal

Once lands and the any-sdk dependency is bumped:

  1. Read StatusCode from the invoker result in internal/stackql/execution (monoValentExecution.GetExecutor): exempt 404 by value, error on other 4xx/5xx under strict upstream error semantics (MCP only).
  2. Classify by value in internal/stackql/mcpbackend (classifyBackendError), keeping the wire contract (http_status, retryable) unchanged.
  3. Delete upstreamStatusCodeRegex (both copies), upstreamNotFoundLooseRegex and the text handling in isUpstreamNotFound.

The behaviour contract is already pinned by robot scenarios in test/robot/functional/mcp.robot and stays unchanged as the regression net:

MCP HTTP Upstream 403 Surfaces As Non Retryable Tool Error
MCP HTTP Upstream 429 Surfaces As Retryable Tool Error
MCP HTTP Upstream 404 Returns Empty Result Set

Depends on

, plus the next any-sdk release/bump.

Activity

  1. self-assigned this
    on Jul 3, 2026
  2. changed the title [-][FEATURE] Consume the naked upstream HTTP status code from any-sdk and remove response-text munging[/-] [+][FEATURE] Consume typed upstream HTTP status from omnisdk and remove response-text munging[/+] on Nov 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions