agents: sandbox guardrails (contract 0.3.0 mirror)#74
Merged
Conversation
…ork watchdog (contract 0.3.0) TypeScript mirror of chdb feat/agents-gate-g3 (vendored descriptors.json / cases.jsonl / CONTRACT.md byte-identical, hint strings byte-identical): - Engine-side row bound (max_result_rows=cap+1, break); optional maxMemoryUsage / maxResultBytes; per-call maxRows clamped. - Resource errors (158/159/241/307/396) -> ChDBResourceError with a model-facing hint; ACCESS_DENIED renamed ALLOWLIST_DENIED. - networkTimeout (default 60s): fast-fail engine baseline + Promise.race deadline on url()/s3()/remote()/... queries; expiry throws NETWORK_TIMEOUT with a hint, poisons the tool, parks the session (in-flight native call can't be cancelled). vitest 466 passed / 11 skipped against the locally built addon.
…ng test Mirror of the Python reference fixes: send/receive timeouts join connection_timeout at min(networkTimeout, 10) — the TLS handshake is bounded by max(send, receive), so the old nt-sized values defeated fast-fail. An engine-side Poco::TimeoutException on a network-source query now carries the same hint as a watchdog expiry. Re-vendored CONTRACT.md + cases.jsonl. Node-specific: a parked watchdog-abandoned session is now closed once its native call settles — chdb-node binds one data directory per process, so leaving it live forever would block every future tool, making the 'create a new ChDBTool' advice unactionable. The real-hang test (local black-holed TLS endpoint) covers both the watchdog and the fresh-tool recovery. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
Author
|
@chibugai, please review it |
There was a problem hiding this comment.
Pull request overview
Updates the agents integration to mirror contract 0.3.0, adding sandbox guardrails that enforce result/resource caps, provide model-facing recovery hints, and introduce a binding-side network watchdog for network-source table functions.
Changes:
- Adds engine-side row bounding (
max_result_rows = maxRows + 1,result_overflow_mode='break') plus optionalmaxMemoryUsage/maxResultBytes, and clamps per-callmaxRowsto the constructor cap. - Introduces
ChDBResourceErrorclassification for resource-limit engine codes and attaches binding-identical recovery hints; adds truncation hints on truncated envelopes. - Implements a network watchdog (
networkTimeout) for network-source queries, poisoning the tool on deadline expiry and parking sessions safely until the in-flight native call settles.
Reviewed changes
Copilot reviewed 15 out of 15 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| test/v3/integrations/agents-tool.test.ts | Adds tests for resource caps, truncation hints, resource-limit error typing, and network watchdog poisoning/behavior. |
| test/v3/integrations/agents-conformance.test.ts | Wires new contract fields into tool creation and asserts hint presence/absence in envelope responses. |
| integrations/agents/tool.mjs | Implements engine-side caps, truncation hinting, network watchdog with poisoning/parking semantics, and renames allowlist error type. |
| integrations/agents/tool.d.mts | Updates public typings for new options and the truncation hint on result objects. |
| integrations/agents/safety.mjs | Adds NETWORK_TABLE_FUNCTIONS set used to detect queries that should be guarded by the watchdog. |
| integrations/agents/safety.d.mts | Exposes typings for NETWORK_TABLE_FUNCTIONS. |
| integrations/agents/index.mjs | Re-exports ChDBResourceError. |
| integrations/agents/index.d.mts | Updates type exports for ChDBResourceError. |
| integrations/agents/errors.mjs | Adds hint support, introduces ChDBResourceError, maps resource-limit codes, and defines RESOURCE_HINT / NETWORK_HINT. |
| integrations/agents/errors.d.mts | Updates typings for hint, resource error class, and exported hint constants. |
| integrations/agents/descriptors.mjs | Bumps contract version to 0.3.0 and advertises new capabilities flags. |
| integrations/agents/descriptors.json | Bumps contract_version to 0.3.0. |
| integrations/agents/descriptors.d.mts | Adds typings for new capability flags. |
| integrations/agents/CONTRACT.md | Updates normative text for 0.3.0: engine caps, resource errors/hints, allowlist rename, network watchdog semantics. |
| integrations/agents/conformance/cases.jsonl | Updates fixture header to 0.3.0 and adds/updates cases for allowlist rename, hints, engine row bound, and watchdog baseline. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Mirrors the Python fix: '' silently disabled the watchdog instead of raising INVALID_ARGUMENT.
Contributor
Author
|
@wudidapaopao please review this PR. |
wudidapaopao
approved these changes
Jul 20, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
TypeScript mirror of chdb-io/chdb#613 (contract 0.3.0). Vendored
descriptors.json/cases.jsonl/CONTRACT.mdbyte-identical to the Python repo; hint strings byte-identical.max_result_rows = maxRows + 1, break mode); optionalmaxMemoryUsage/maxResultBytes; per-callmaxRowsclamped to the constructor cap.ChDBResourceErrorwith a model-facing hint;ACCESS_DENIEDrenamedALLOWLIST_DENIED.networkTimeout(default 60s): fast-fail HTTP baseline + aPromise.racedeadline onurl()/s3()/remote()... queries; expiry throwsNETWORK_TIMEOUTwith a hint and poisons the tool (the in-flight native call can't be cancelled — same semantics and CONTRACT P5 text as Python).Tests: full v3 vitest suite 466 passed / 11 skipped against the locally built addon (agents suites 56/56, conformance 33 cases).
🤖 Generated with Claude Code
Note
Add sandbox guardrails to agents tool matching contract 0.3.0
resource_capsandnetwork_watchdogcapability flags.ChDBResourceErrorin errors.mjs for engine resource-limit codes (158, 159, 241, 307, 396), attaching aRESOURCE_HINTrecovery instruction to each.networkTimeout(default 60s); on expiry, the tool enters a poisoned state, parks the in-flight session, and throwsNETWORK_TIMEOUTwith a hint.ChDBToolconstructor options (maxMemoryUsage,maxResultBytes,maxResultRows) configure engine-side caps viaresult_overflow_mode='break'; truncated results include aTRUNCATION_HINTin the envelope.ACCESS_DENIEDtoALLOWLIST_DENIED. Risk: this is a breaking change for callers that match on the old error type string.Macroscope summarized 97c893b.