[PR #395] [MERGED] feat(custom-extension): surface hook 4xx/5xx status to API callers #401

New issue

Closed

opened 2026-10-29 14:23:00 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-29 14:23:00 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/kvcache-ai/AgentENV/pull/395
Author: @guozy18
Created: 10/20/2026
Status: ✅ Merged
Merged: 10/20/2026
Merged by: @yingdi-shan

Base: main ← Head: sync/extension-status-errors

📝 Commits (1)

879dc5f feat(custom-extension): surface hook 4xx/5xx status to API callers

📊 Changes

4 files changed (+256 additions, -12 deletions)

View changed files

📝 docs/src/concepts/custom-extension/lifecycle-hooks.md (+6 -0)
📝 src/api/impls/sandbox.rs (+142 -6)
📝 src/sandbox/custom_extension/client.rs (+107 -6)
📝 src/sandbox/custom_extension/mod.rs (+1 -0)

📄 Description

What

Preserve custom-extension HTTP failures and distinguish caller rejection from extension server errors.

Why

An extension 4xx rejection was reported as a server error on launch/resume paths, while a patch hook 5xx could be reported as a client error.

N/A — focused synchronization of an existing implementation.

Scope and non-goals

Typed hook errors, API error classification, original regression tests, one main-branch fork-result regression, and lifecycle documentation.

Design and behavior changes

Map hook 4xx to 400 for create/cold-create/connect/fork/patch, and to 409 on resume. Map hook 5xx to server errors. Keep main-branch volume rollback before returning. Classify per-child fork results as well as whole-operation errors; v2 wrappers reuse the existing mappings. Preserve best-effort stop behavior.

Compatibility and operations

Public API or generated protocol: Error status classes now reflect extension rejection versus server failure; messages include hook status and response content.
Configuration or defaults: No configuration changes.
Snapshot manifest, artifact layout, or storage format: unchanged.
Upgrade and rollback: ordinary code upgrade/revert; no data migration.
Host requirements, permissions, ports, or dependencies: unchanged.

Validation

Validated on upstream main 949cec2 plus this single commit, independently of the other synchronization PRs.

PASS: make fmt
PASS: cargo clippy --locked -p agentenv --all-targets --all-features -- -D warnings
PASS: cargo test --locked -p agentenv --lib sandbox::custom_extension::client::tests (14 tests)
PASS: cargo test --locked -p agentenv --lib api::impls::sandbox::tests::hook_ (3 tests)
PASS: cargo test --locked -p agentenv --lib fork_result_error_preserves_extension_rejection (1 test)
PASS: git diff --check

Clippy and all 18 focused tests ran on Linux as a non-root user. Full workspace tests and VM lifecycle E2E were not rerun for this PR.

Risks and reviewer notes

Clients may observe 4xx instead of 500. Extension error bodies become visible to API callers. The retained tests exercise hook 4xx/5xx responses, nested error propagation and per-child fork-result classification. Full VM lifecycle E2E was not rerun for this PR.

The original author, author date and commit message are preserved. Main-branch adaptations are described above.

Checklist

One coherent change with no unrelated refactors.
Regression coverage included; execution limitations are stated.
No credentials or private deployment configuration included.
Generated code, where changed, was regenerated from the updated schema.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/kvcache-ai/AgentENV/pull/395 **Author:** [@guozy18](https://github.com/guozy18) **Created:** 10/20/2026 **Status:** ✅ Merged **Merged:** 10/20/2026 **Merged by:** [@yingdi-shan](https://github.com/yingdi-shan) **Base:** `main` ← **Head:** `sync/extension-status-errors` --- ### 📝 Commits (1) - [`879dc5f`](https://github.com/kvcache-ai/AgentENV/commit/879dc5ff192682d9046fc79f76eb89f95ddb9d8d) feat(custom-extension): surface hook 4xx/5xx status to API callers ### 📊 Changes **4 files changed** (+256 additions, -12 deletions) <details> <summary>View changed files</summary> 📝 `docs/src/concepts/custom-extension/lifecycle-hooks.md` (+6 -0) 📝 `src/api/impls/sandbox.rs` (+142 -6) 📝 `src/sandbox/custom_extension/client.rs` (+107 -6) 📝 `src/sandbox/custom_extension/mod.rs` (+1 -0) </details> ### 📄 Description ## What Preserve custom-extension HTTP failures and distinguish caller rejection from extension server errors. ## Why An extension 4xx rejection was reported as a server error on launch/resume paths, while a patch hook 5xx could be reported as a client error. ## Related issue N/A — focused synchronization of an existing implementation. ## Scope and non-goals Typed hook errors, API error classification, original regression tests, one main-branch fork-result regression, and lifecycle documentation. ## Design and behavior changes Map hook 4xx to 400 for create/cold-create/connect/fork/patch, and to 409 on resume. Map hook 5xx to server errors. Keep main-branch volume rollback before returning. Classify per-child fork results as well as whole-operation errors; v2 wrappers reuse the existing mappings. Preserve best-effort stop behavior. ## Compatibility and operations - Public API or generated protocol: Error status classes now reflect extension rejection versus server failure; messages include hook status and response content. - Configuration or defaults: No configuration changes. - Snapshot manifest, artifact layout, or storage format: unchanged. - Upgrade and rollback: ordinary code upgrade/revert; no data migration. - Host requirements, permissions, ports, or dependencies: unchanged. ## Validation Validated on upstream main `949cec2` plus this single commit, independently of the other synchronization PRs. ```text PASS: make fmt PASS: cargo clippy --locked -p agentenv --all-targets --all-features -- -D warnings PASS: cargo test --locked -p agentenv --lib sandbox::custom_extension::client::tests (14 tests) PASS: cargo test --locked -p agentenv --lib api::impls::sandbox::tests::hook_ (3 tests) PASS: cargo test --locked -p agentenv --lib fork_result_error_preserves_extension_rejection (1 test) PASS: git diff --check ``` Clippy and all 18 focused tests ran on Linux as a non-root user. Full workspace tests and VM lifecycle E2E were not rerun for this PR. ## Risks and reviewer notes Clients may observe 4xx instead of 500. Extension error bodies become visible to API callers. The retained tests exercise hook 4xx/5xx responses, nested error propagation and per-child fork-result classification. Full VM lifecycle E2E was not rerun for this PR. The original author, author date and commit message are preserved. Main-branch adaptations are described above. ## Checklist - [x] One coherent change with no unrelated refactors. - [x] Regression coverage included; execution limitations are stated. - [x] No credentials or private deployment configuration included. - [x] Generated code, where changed, was regenerated from the updated schema. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-29 14:23:00 +00:00