TanStack AI: a run_code server tool
Shotcup has no package for TanStack AI. A TanStack AI server tool that calls Shotcup's REST API gives your model a run_code tool in a few lines. For code mode, the program it runs can also call your own tools (below).
The tool
TanStack AI defines a tool with toolDefinition and gives it a server implementation with .server(), which returns the tool you pass to chat():
import { toolDefinition } from "@tanstack/ai";
import { z } from "zod";
const runCodeDef = toolDefinition({
name: "run_code",
description:
"Runs JavaScript (ES modules, arrow functions, const/let, for...of; no npm, no Node APIs besides fs) " +
"in a fresh Shotcup sandbox. Print the answer; write files under /out.",
inputSchema: z.object({ code: z.string() }),
outputSchema: z.object({
status: z.string(),
error: z.string().nullable(),
stdout: z.string(),
stderr: z.string(),
hint: z.unknown(),
artifacts: z.array(z.object({ path: z.string(), url: z.string().optional() })),
}),
});
export const runCode = runCodeDef.server(async ({ code }, context) => {
const response = await fetch("https://shotcup.dev/api/v1/runs", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SHOTCUP_API_KEY}`,
"Content-Type": "application/json",
// optional: tells Shotcup the run came from this guide
"X-Shotcup-Integration": "tanstack-ai",
},
body: JSON.stringify({ code }),
signal: context?.abortSignal,
});
const data = await response.json();
if (!response.ok) throw new Error(`Shotcup: ${data.error.code}: ${data.error.message}`);
const { status, error, stdout, stderr, hint, artifacts } = data.run;
return { status, error, stdout, stderr, hint, artifacts: artifacts.map(({ path, url }) => ({ path, url })) };
});Then hand it to chat() with your adapter:
import { chat, toServerSentEventsResponse } from "@tanstack/ai";
export async function POST(request: Request) {
const { messages } = await request.json();
const stream = chat({ adapter, messages, tools: [runCode] });
return toServerSentEventsResponse(stream);
}A run that fails is still an answer: status is failed, and error and stderr say why. When the code used a construct the language profile leaves out, hint says what to write instead, so the model can correct its code and call the tool again. When the chat is aborted, the tool's abortSignal closes the request, which cancels the run. The quickstart has the rest of the request and the answer.
Your own tools inside the program
For code mode, the program calls your functions as tools.<name>(...) while it runs. Declare them with the run and answer each call over the stream endpoint, as the code mode page shows, or with the shotcup SDK's tool handlers once it is published to npm:
const run = await shotcup.runs.create(
{ code },
{ tools: { crm: { listCustomers: async (query) => crm.customers(query) } } },
);Tell the model which functions exist in the tool's description.
Two kinds of approval
TanStack AI's needsApproval on a tool definition asks before the model's call to run_code runs at all. Shotcup's approval: true on a declared tool pauses the program itself at that call, so a person approves the one refund the program wants to make rather than the whole program. Durable code mode shows how a paused run is resumed. The two can be used together.
This page as Markdown: /docs/tanstack-ai.md