Conversation
The tools that let an agent read and change workspace files were each written against one specific agent library. The description the model reads, the rules about what a valid request looks like, and the code that does the work were all tangled together with that library's way of declaring a tool. That was fine while there was only one library to support. It meant that supporting a second one would have required copying every tool and keeping the copies in step by hand. Describe each tool once instead, in a form that mentions no library at all, and keep the list of which tools exist in a single place. The existing support is now a thin translation layer on top of that description, and it behaves exactly as it did before. A tool can also say how it wants its result shown to the model: ordinary text, a failure, structured data, or a picture. Each library then renders that in whatever way it supports.
Agents built on pi or TanStack AI could not use the workspace tools without writing their own wrappers around the file and command surfaces first. Add support for both, so the same tools are available whichever of the three libraries an agent is built on, with the same names, the same descriptions, and the same limits. The two libraries expect to be handed tools in different shapes, and each is served in the shape it wants. pi keeps the list of available tools separate from the code that runs them, and expects the surrounding program to run them itself. So it gets both pieces together: the list to show the model, and something that takes the model's request, checks it, and runs it. A bad request or a tool that fails comes back as an ordinary failed result, which the model can learn from and try again, rather than as a crash that would stop the program. TanStack AI wants each tool to hand back a single answer, so a long-running command reports the state of the run once it has finished, with the option of also reporting progress along the way. Neither addition pulls in the original library, so installing one of the three does not drag in the other two.
Support for the two new libraries was added by reducing all three to the small set of things the original one needed. That shared the code, but it also meant throwing away features the new libraries have and the original does not. Anyone using them through this package got less than they would have by wiring the tools up themselves. Let each tool state a few plain facts about itself instead: whether it changes files, whether its request is the sort a model is likely to get subtly wrong, and whether it reports progress while it runs. Every tool states these once. Each library then makes what use of them it can and quietly ignores the rest, so sharing the code no longer means settling for the least capable option. This buys something real in both. Some requests are easy to get wrong, because they carry an exact copy of a piece of a file or a position part way through one, and a wrong guess wastes a turn. pi can ask the model provider to hold the model to the expected shape as it writes the request, so those mistakes are prevented rather than reported. Where a provider cannot do this, the request is simply sent the ordinary way, because refusing to run at all would be worse. TanStack AI is told the shape of a successful answer for the tools that always answer the same way, which saves the caller describing it again. It can also be asked to confirm with the user before any tool that changes files, without having to list them, and to keep tools out of sight until the model goes looking for them.
馃 Changeset detectedLatest commit: 8fa5a18 The changes in this PR will be included in the next version bump. This PR includes changesets to release 4 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
There was a problem hiding this comment.
馃攳 SDK contracts remain untested
Tests call locally declared shapes instead of either supported SDK. Contract drift can pass without exercising real Pi or TanStack integration.
(Refers to this code)
Was this helpful? React with 馃憤 or 馃憥 to provide feedback.
| specs: ToolSpecSet, | ||
| options: Omit<CreateTanStackToolsOptions, keyof CreateToolsOptions> = {}, | ||
| ): TanStackToolSet { | ||
| const tools: TanStackToolSet = {}; |
There was a problem hiding this comment.
馃敶 TanStack chat rejects tool set
Passing createTanStackTools() to chat fails because chat iterates an array, while tools is a record. No TanStack tool can run.
Learn more
Supported TanStack AI versions declare chat({ tools }) as a readonly array and call array methods on it during setup. The adapter instead builds an object keyed by tool name. The documented usage passes that object directly, so setup fails before the request begins.
Example: chat({ adapter, messages, tools: createTanStackTools({ workspace }) }) receives { read, ls, ... }. TanStack expects [read, ls, ...] and cannot iterate the record.
Recommended fix: Return a TanStack-compatible tool array from createTanStackTools and toTanStackTools. If a keyed registry is also useful, expose it through a separate API rather than using it as the chat input.
Was this helpful? React with 馃憤 or 馃憥 to provide feedback.
| // Only a successful result is described. The error branch is a | ||
| // normal outcome, so validating every return against the success | ||
| // shape would reject legitimate error results. | ||
| outputSchema: spec.outputSchema, |
There was a problem hiding this comment.
馃煛 Tool errors fail output validation
When a mutation returns { error }, outputSchema rejects it because the schema only accepts success. TanStack reports a validation failure instead.
Learn more
TanStack validates every value returned by a server tool when outputSchema is present. The registered mutation schemas describe only successful results, but these executors return normal error objects for filesystem failures. The adapter preserves that error object, so TanStack rejects it against the success schema and changes the result into a generic execution failure.
Example: A read-only filesystem makes write return { error: "read-only filesystem" }. TanStack validates that against { path, bytesWritten } and reports Output validation failed for tool write instead of returning the original error object.
Recommended fix: Either include each executor's error branch in its outputSchema, or omit outputSchema for executors whose normal return union includes errors.
Was this helpful? React with 馃憤 or 馃憥 to provide feedback.
| // Strict schemas require every property, expressing "absent" as | ||
| // null, so drop those before validating against the Zod schema | ||
| // where the field is genuinely optional. | ||
| const parsed = spec.inputSchema.safeParse(dropNulls(call.arguments ?? {})); |
There was a problem hiding this comment.
馃煛 Null callable input gets dropped
A pi exec call with input: null reaches the callable backend as undefined. dropNulls removes this valid structured input.
Learn more
Pi's strict schemas encode omitted optional fields as null, so the adapter removes null-valued keys before Zod validation. It applies that conversion to every tool, including exec, even though exec.input accepts any JSON value and null is meaningful. The executor therefore cannot distinguish an explicitly supplied null input from an omitted input.
Example: A callable JavaScript module expects input === null. The model calls exec with { "command": "...", "input": null }, but the module receives undefined.
Recommended fix: Remove placeholder nulls only for fields made nullable by this adapter's strict-schema transformation. Do not remove null from fields whose original Zod schema accepts it, including exec.input.
Was this helpful? React with 馃憤 or 馃憥 to provide feedback.
| "./tools/pi": { | ||
| "types": "./dist/tools/pi.d.ts", | ||
| "import": "./dist/tools/pi.js" | ||
| }, | ||
| "./tools/tanstack": { | ||
| "types": "./dist/tools/tanstack.d.ts", | ||
| "import": "./dist/tools/tanstack.js" | ||
| }, |
There was a problem hiding this comment.
馃攳 Public API change lacks changeset
Two public entrypoints and their APIs will ship without release notes or a version bump. Repository release rules require a changeset.
Was this helpful? React with 馃憤 or 馃憥 to provide feedback.
commit: |
Add one example per new library, each a one-shot agent: post a task, it works in a durable workspace, it replies when done. Both use the Workers AI binding, so neither needs an API key. The two examples exist to show the difference in shape. The pi one writes the loop out in full, because pi keeps the tool list apart from the code that runs the tools and expects the surrounding program to do the running. The TanStack AI one has no loop at all, because chat() owns it, so the agent is about ten lines. Seeing them side by side is the clearest statement of what each library takes on. The Workers AI provider for pi is lifted from the pi harness example in cloudflare/agents, cut down to the one model this example uses. Writing these turned up a mistake in the tool documentation, now fixed: chat() takes tools as a list, not keyed by name. The set is still returned keyed by name, which is what a server-side registry wants, so the examples pass Object.values(tools). A tool also needs a phantom marker to satisfy the union chat() accepts, and its execute takes the validated arguments loosely, matching the signature chat() calls it with.
Running both example agents against a scripted model, rather than only typechecking them, turned up two real faults. A script per example now drives its loop locally with no Cloudflare account, so the next person can reproduce either in one command. A tool that failed reported the wrong reason under TanStack AI. It validates every value a tool returns against the tool's output shape, and those shapes described only success, so an ordinary failure such as a missing file was replaced by a complaint about the shape. The model was told the output was malformed instead of what went wrong. The shapes now describe failure too, because for a filesystem tool a failure is an ordinary outcome rather than a fault. A deliberate null was lost under pi. Strict argument checking makes every field required and sends an omitted one as null, so those nulls were stripped before use. They were stripped from every field of every tool, including one that accepts any value at all, so a caller passing null to a command could not be told apart from one passing nothing. Only the fields the strict transformation widened are stripped now. Both faults have a test that fails without the fix, and a changeset covers the new entrypoints.
Every TanStack entry point takes an array: chat(), mergeAgentTools and createToolRegistry all call array methods on what they are given. The tools came back keyed by name instead, so each caller had to convert, and the docs and both examples carried that conversion. The record was also a trap rather than merely inconvenient. createToolRegistry rejected it outright, but mergeAgentTools accepted it without complaint and returned something still keyed by name, so the failure surfaced later inside chat() as a missing array method and pointed away from its cause. A list is what the library consumes, so a list is what these builders return. tanStackToolsByName covers the rarer case of reaching one tool directly, such as adjusting a single tool before the call. An earlier note claimed a server-side registry wanted the record. It does not; mergeAgentTools is typed ReadonlyArray on that argument, and nothing in the library asks for the keyed shape.
Replaces the separate tanStackToolsByName helper with a `format` option on the builders, so one call site covers both shapes. It defaults to "array", which every TanStack entry point takes, so the common path is unchanged and needs no argument. "object" keys the same tools by name for a caller that reaches one directly. The option is generic rather than a plain union, so the return type follows from the literal: passing "object" types the result as a record and "array" or nothing types it as a list. A caller that passes a computed format gets the union and has to narrow, which is honest about what it asked for.
1 participant
Add support for Pi and Tanstack AI tools alongside AI SDK.
This makes it easier to get started wiring up an agent and a computer workspace.
All three offer the same tools with the same names, descriptions and limits.
Usage for a Pi harness.
Usage for Tanstack AI: