fix(sdk): avoid ERROR-level logs for expected file-not-found on read

[hittyt]

Summary

The Kotlin SDK's FilesystemAdapter read operations (readFile / readByteArray / readStream) catch every failure and log it at ERROR with a full stack trace before rethrowing.

A missing file is not a fault — the execd server returns HTTP 404 with body {"code":"FILE_NOT_FOUND", ...}, which is an expected, business-level outcome. Logging it at ERROR floods callers' error logs and monitoring with stack-trace noise for a perfectly normal control-flow case (e.g. polling for a not-yet-created stdout file). Reported by a user whose service was producing large volumes of ERROR logs like:

ERROR - c.a.o.s.i.a.s.FilesystemAdapter - Failed to read file with encoding UTF-8: /home/admin/mcp/mcp-proxy.stdout
com.alibaba.opensandbox.sandbox.domain.exceptions.SandboxApiException: Failed to read file. Status code: 404,
  Body: {"code":"FILE_NOT_FOUND","message":"file not found ... no such file or directory"}
    at ...FilesystemAdapter.readFile(FilesystemAdapter.kt:99)

Note the logger is FilesystemAdapter itself — the SDK emits this, not the caller, so callers cannot control the level.

This change distinguishes "file not found" from genuine failures and logs the former at DEBUG. The exception is still propagated to the caller unchanged, so error-handling behavior is unaffected.

• Add SandboxError.FILE_NOT_FOUND constant.
• Add Throwable.isFileNotFound() extension (statusCode == 404 or error.code == FILE_NOT_FOUND) so callers can branch on the not-found case cleanly too.
• Route read-failure logging through a new logReadFailure() helper that downgrades not-found to DEBUG and keeps ERROR for real failures.

Scope is intentionally limited to the read paths where the noise was reported. The broader log-and-throw pattern across the adapter (write/delete/etc.) is left for a follow-up.

Testing

• Unit tests
• Integration tests
• e2e / manual verification

Added FilesystemAdapterTest (5 cases, all passing via ./gradlew :sandbox:test):

• readFile surfaces FILE_NOT_FOUND + statusCode 404 on a 404 response (so callers can distinguish it)
• readFile returns content on success (regression guard)
• isFileNotFound() true for FILE_NOT_FOUND, false for other API errors, false for non-sandbox exceptions

Breaking Changes

• None

Public exception types and propagation are unchanged; only the SDK's internal log level for the not-found case changes (ERROR → DEBUG). A new error-code constant and extension function are additive.

Checklist

• Linked Issue or clearly described motivation
• Added/updated docs (if needed)
• Added/updated tests (if needed)
• Security impact considered
• Backward compatibility considered

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0c0e5ecbfb

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[hittyt]

Thanks for the review — good catch, addressed in 29fab0b.

You're right that a bare HTTP 404 is ambiguous. A 404 whose body can't be parsed is mapped to UNEXPECTED_RESPONSE, and silently downgrading those to DEBUG would hide real endpoint/routing/config regressions. I removed the || statusCode == 404 fallback so isFileNotFound() now classifies as not-found only when the server returns the explicit FILE_NOT_FOUND code (which execd does for missing files). Anything else stays loud at ERROR.

Added a regression test (isFileNotFound is false for a 404 without an explicit FILE_NOT_FOUND code) to lock this in.

[ninan-nn]

LGTM