---
title: "TanStack AI: a run_code server tool"
description: "A TanStack AI server tool that runs model-written code through the REST API, with your own tools and approvals for code mode."
canonical: "https://shotcup.dev/docs/tanstack-ai"
last_updated: "2026-10-18"
---
# 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](https://shotcup.dev/docs/code-mode), the program it runs can also call your
own tools ([below](#your-own-tools-inside-the-program)).

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

```ts
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:

```ts
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](https://shotcup.dev/docs/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](https://shotcup.dev/docs/code-mode#the-same-program-with-live-tools)
shows, or with the `shotcup` SDK's tool handlers once it is published to
npm:

```ts
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](https://shotcup.dev/docs/durable-code-mode) shows how a paused run is
resumed. The two can be used together.
