integrations(agents): align to the cross-language agent-tool contract#66
Merged
Merged
Conversation
chdb-node's agent tools predated chdb's cross-language agent-tool contract
(chdb-io/chdb chdb/agents/CONTRACT.md) and only implemented a 3-method
subset with different names, no param binding, and no shared error/64-bit/
resource semantics. This ports the contract's base faithfully so the TS
binding is contract-conformant and the Python/TS surfaces stay in lock-step.
Base (integrations/agents/, mirrors chdb.agents):
- tool.mjs: ChDBTool with the full canonical method set — run_select_query,
list_databases, list_tables, describe_table, get_sample_data,
list_functions, attach_file — plus toolSpecs()/call().
- P1 read-only via SET readonly=2 (immutable, opt out with readOnly:false);
P2 values bound as {name:Type} params, identifiers via quoteIdent; P3
maxRows + maxBytes with a truncated flag; P4 call() returns the
{ok,result}|{ok,error} envelope and query() rejects with typed errors.
- errors.mjs: parseError with the same regex + code map as the reference
(164->READONLY, 62->SYNTAX, 46/47/60/81/115->UNKNOWN_*).
- safety.mjs: quoteIdent/quoteString/pathAllowed/scanFilePaths.
- 64-bit ints returned exact (output_format_json_quote_64bit_integers=1);
P5 max_execution_time / file_allowlist / attachments+attach_file.
- The Python-only dataframe_query is intentionally omitted (language-specific,
outside the cross-language base).
Framework adapters are now thin shims over the base:
- ai-sdk.mjs and mastra.mjs build the same canonical tool set from a shared
descriptor list and delegate every call to ChDBTool.call(), so both
frameworks expose identical behavior. Removed chdb-tool-core.mjs.
- New framework-agnostic entry point: import { ChDBTool } from 'chdb/agents'.
Contract + conformance vendored:
- integrations/agents/CONTRACT.md and conformance/{cases.jsonl,fixtures,README}
are synced mirrors of the canonical files in chdb-io/chdb.
- test/v3/integrations/agents-conformance.test.ts is the TS twin of the Python
reference runner over the same fixture: 16/16 cases pass. Full integration
suite 46/46.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Contributor
Author
|
@chibugai, review it. |
There was a problem hiding this comment.
Pull request overview
Aligns chdb-node’s agent integrations (AI SDK + Mastra) to the cross-language ChDBTool contract used by chdb-io/chdb, including a shared conformance fixture and a new framework-agnostic chdb/agents entry point.
Changes:
- Introduces
integrations/agents/ChDBToolimplementing the canonical contract tool surface (P1–P5), plus shared error parsing and safety helpers. - Refactors
integrations/ai-sdkandintegrations/mastraadapters into thin shims overChDBTool.call()using a shared descriptor list. - Vendors the contract + conformance fixture and adds a TypeScript conformance runner test.
Reviewed changes
Copilot reviewed 22 out of 22 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| test/v3/integrations/mastra.test.ts | Updates Mastra adapter tests to assert canonical tool names and envelope-shaped results. |
| test/v3/integrations/ai-sdk.test.ts | Updates AI SDK adapter tests for canonical toolset, param binding, read-only envelope errors, and 64-bit JSON behavior. |
| test/v3/integrations/agents-conformance.test.ts | Adds TS conformance runner that executes the vendored cases.jsonl against ChDBTool. |
| package.json | Adds ./agents subpath export for the new framework-agnostic entry point. |
| integrations/mastra.mjs | Replaces legacy 3-tool implementation with canonical toolset built from descriptors and delegated to ChDBTool.call(). |
| integrations/mastra.d.mts | Updates Mastra typings to expose canonical tool names and envelope return type; re-exports agent error/tool types. |
| integrations/chdb-tool-core.mjs | Removes superseded legacy framework-agnostic executor core. |
| integrations/ai-sdk.mjs | Replaces legacy 3-tool implementation with canonical toolset built from descriptors and delegated to ChDBTool.call(). |
| integrations/ai-sdk.d.mts | Updates AI SDK typings to expose canonical tool names and envelope return type; re-exports agent error/tool types. |
| integrations/agents/tool.mjs | Adds the core ChDBTool implementation (query, introspection, attachments, call-envelope dispatch). |
| integrations/agents/tool.d.mts | Adds TypeScript typings for ChDBTool, QueryResult, and the tool-dispatch envelope. |
| integrations/agents/safety.mjs | Adds shared quoting + allowlist helpers (quoteIdent, quoteString, scanFilePaths, pathAllowed). |
| integrations/agents/safety.d.mts | Adds typings for safety helpers. |
| integrations/agents/index.mjs | Adds chdb/agents entry point exporting tool, errors, and safety helpers. |
| integrations/agents/index.d.mts | Adds typings for chdb/agents entry point exports. |
| integrations/agents/framework.mjs | Adds shared framework glue: resolveTool() and canonical descriptor list with schemas. |
| integrations/agents/errors.mjs | Adds shared error classes + parseError() to classify engine errors into typed failures. |
| integrations/agents/errors.d.mts | Adds typings for error objects and error classes. |
| integrations/agents/CONTRACT.md | Vendors the upstream cross-language agent-tool contract doc. |
| integrations/agents/conformance/README.md | Vendors upstream conformance fixture documentation. |
| integrations/agents/conformance/fixtures/sample.csv | Adds vendored fixture data for conformance cases. |
| integrations/agents/conformance/cases.jsonl | Adds vendored conformance cases executed by the TS runner. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
chibugai
reviewed
Jul 2, 2026
…or paths Addresses the resource-lifetime review findings on the agent tools (the behavioral pillars already match the reference, so only the leaks are fixed): - ChDBTool constructor: if setup (SET queries / attachment views / the read-only lock) throws after the owned Session is created, close that Session before re-throwing — the constructor never returns, so the caller otherwise has no handle to close() and the temp dir + native handle leak. - ai-sdk / mastra chdbTools(): expose a non-enumerable close() on the returned toolset (and on chdbQueryTool's tool) that closes the Session the toolset owns. Non-enumerable so the frameworks don't treat it as a tool; a no-op when the caller passed their own session/tool. Types + docs updated. Adds test/v3/integrations/agents-tool.test.ts covering the constructor error-path cleanup, close() idempotency, caller-owned sessions being left open, and the non-enumerable toolset close(). Integration suite 50/50. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
ShawnChen-Sirius
force-pushed
the
feat/agents-contract
branch
from
60d8df5 to
d97d2df
Compare
wudidapaopao
approved these changes
Jul 2, 2026
ShawnChen-Sirius
added a commit
that referenced
this pull request
Jul 7, 2026
…w integrations Additive minor release on top of 3.1.0 (2026-06-24). No breaking changes; existing 3.1.0 APIs continue to work unchanged. libchdb bits are unchanged (chdb-core v26.5.1-rc.1 packaged as @chdb/lib-* 26.5.2 — no republish needed, the subpackage-matrix job will idempotent-skip). ## What's new ### Layer 3 fluent query builder SDK (#55, #59) First-class typed fluent query API — Kysely-/Drizzle-style: const db = connect({ session }) const rows = await db .from('users') .where(r => r.age.gt(18)) .select('id', 'name') .execute() - `src/layer3/{builder,execute,compile,dialect,introspection,connect,types,codegen}/` - `chdb-gen-types` CLI — generates row types from a schema (Drizzle / Prisma / raw SQL sources) - `.stream()` terminal with server-side parameter binding - Arrow C Data Interface support: register JS columnar data as `arrowstream()` tables - 12 new test files under `test/v3/layer3/` ### Cross-language agent-tool contract + 2 framework adapters (#61, #66) - `chdb/ai-sdk` — Vercel AI SDK tools (`generateText`/`streamText`) - `chdb/mastra` — Mastra tools + `ChDBVector` (HNSW RAG store) + `ChDBStore` - Both are thin wrappers over `ChDBTool.call()` from `integrations/agents/`, which implements the cross-language contract vendored from `chdb-io/chdb` (`chdb/agents/CONTRACT.md`, chdb-io/chdb#597). - 7 canonical tools: `run_select_query` / `list_databases` / `list_tables` / `describe_table` / `get_sample_data` / `list_functions` / `attach_file` - 5 pillars enforced: engine-level readonly=2 (P1), value-vs-identifier separation (P2), truncation flag (P3), error envelope for model self-correction (P4), resource/source controls (P5) - Behavior verified against the shared `conformance/cases.jsonl` fixture ### `chdb/hypequery` DatabaseAdapter (#63, #65) Lets `@hypequery/clickhouse` query builder run on embedded chDB instead of a remote ClickHouse server. Uses hypequery's own `substituteParameters` (imported, not copied) so rendered SQL stays byte-identical to hypequery's built-in HTTP adapter. ### `chdb/connection` stabilization for @clickhouse/client 1.23.0 - `peerDependency: "@clickhouse/client: >=1.23.0"` (optional) — old client triggers a clear npm warning instead of a runtime TS error - Parity runner switched to track `ClickHouse/clickhouse-js` release tag `client-1.23.0` (per the sync-policy table; #52 shipped the initial hook) - Runner auto-detects upstream Vitest layout (pre-/post-clickhouse-js#931) - Runner re-synced when clickhouse-js reorganized into a monorepo (#62) ### AI-discovery docs (#60) - Top-level `AGENTS.md` + `llms-full.txt` - Per-subpath `AGENTS.md` (`src/layer3/`, `src/connection/`, etc.) - All packaged in `files` so agents crawling the installed tarball find them ## Fixes / infrastructure - Bind `null` / `undefined` query params as SQL `\N` (contributor @dfrankland, #68) — matches `@clickhouse/client` behavior - `close()`-mid-flight engine abort + ResultSet teardown race (#56) - `ChDBVector` HNSW granularity / filter binding / dimension guard (#61) - Release workflow: publish → `unverified` dist-tag → clean-install verify matrix → promote to `latest` (#64). A broken release now never reaches `latest` users. - CI: cache deps + harden npm registry fetch against transient resets ## User-facing installation matrix ``` npm install chdb # base + Layer 3 SDK npm install chdb @clickhouse/client # + chdb/connection npm install chdb @hypequery/clickhouse # + chdb/hypequery npm install chdb ai zod # + chdb/ai-sdk npm install chdb @mastra/core zod # + chdb/mastra ``` Native libchdb: chdb-core v26.5.1-rc.1 (packaged as @chdb/lib-* 26.5.2), unchanged from 3.1.0. Generated with [Claude Code](https://claude.ai/code) via [Happy](https://happy.engineering) Co-Authored-By: Claude <[email protected]> Co-Authored-By: Happy <[email protected]>
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.
Brings chdb-node's agent tools into conformance with the cross-language agent-tool contract introduced in chdb-io/chdb (
chdb/agents/CONTRACT.md, see chdb-io/chdb#597). The Pythonchdb.agents.ChDBToolis the reference; this makes the TypeScript binding implement the same methods with the same semantics, verified against the same fixture.Why
The existing
chdb/ai-sdkandchdb/mastratools predated the contract: only 3 methods (chdbQuery/chdbListTables/chdbDescribeSource), different names, no parameter binding, no shared error classification / 64-bit policy / resource controls, and no conformance runner. That's a parallel implementation that can drift from Python — exactly what the contract exists to prevent.The aligned base (
integrations/agents/, mirrorschdb.agents)tool.mjs—ChDBToolwith the full canonical method set:run_select_query,list_databases,list_tables,describe_table,get_sample_data,list_functions,attach_file, plustoolSpecs()/call().SET readonly=2, immutable, opt out withreadOnly:false).{name:Type}params (never concatenated); identifiers viaquoteIdent(backtick-double-escape, reject NUL).maxRows+maxBytesguard with atruncatedflag (never silent).call()returns the{ ok, result } | { ok, error }envelope; direct methods reject with typed errors.errors.mjsuses the same regex + code map as the reference (164→READONLY,62→SYNTAX,46/47/60/81/115→UNKNOWN_*).max_execution_time,file_allowlist,attachments+attach_file.output_format_json_quote_64bit_integers=1).dataframe_query(in-process pandas viaPython()) is intentionally omitted — a language-specific capability outside the cross-language base, per the contract.Frameworks are now thin shims
ai-sdk.mjsandmastra.mjsbuild the identical canonical tool set from one shared descriptor list and delegate every call toChDBTool.call(), so both frameworks (and Python) behave identically. Removedchdb-tool-core.mjs. New framework-agnostic entry point:import { ChDBTool } from 'chdb/agents'.Contract + conformance vendored into chdb-node
integrations/agents/CONTRACT.mdandconformance/{cases.jsonl,fixtures,README}are synced mirrors of the canonical files upstream (provenance noted at the top of each).test/v3/integrations/agents-conformance.test.tsis the TypeScript twin of the Python reference runner, over the samecases.jsonl.Verification
agents-conformance,ai-sdk,mastra,chdb-vector,chdb-store,hypequery).ai/@mastra/core/zodoptional peers.Note: the pre-existing
layer3/{arrow-input,stream}local failures are environmental (they fail identically on a cleanmainhere) and unrelated to this change.🤖 Generated with Claude Code
Note
Implement cross-language agent-tool contract for chDB with typed errors, safety helpers, and seven canonical tools
./agentssubpath export (agents/) implementing the full chDB agent-tool contract:ChDBToolwith engine-enforced read-only mode, parameter binding, result capping with truncation signaling, and structured error envelopes.ChDBError,ChDBReadOnlyError,ChDBSyntaxError,ChDBUnknownObjectError) with aparseError()function that maps engine exception codes and types to the correct subclass.quoteIdent,quoteString,pathAllowed,scanFilePaths) for identifier quoting, string literal escaping, and file path allowlist enforcement.run_select_query,list_databases,list_tables,describe_table,get_sample_data,list_functions,attach_file) withToolEnvelopesemantics and aclose()method.ChDBTool.call().Macroscope summarized d97d2df.