Skip to content

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():

TypeScript
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:

TypeScript
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:

TypeScript
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