AI Chat

This track builds one thing end to end: a durable AI chat app — think a production support-chat surface, the kind of assistant a real product ships next to its docs. By the last chapter you will have a chat whose transcript — messages, streaming markdown, tool-call cards, and MCP widgets — survives reload, reconnect, and a second tab, and whose replies stream in live as the model produces them, because it is backed by a durable session stream rather than component state. That is the differentiator this track proves: most chat UIs keep the conversation in component state, so a refresh, a dropped socket, or a second tab loses it — here the transcript lives in the durable session and the UI is only a view of it, so the same log replays identically on reload, reconnect, and every other tab watching. It runs on shipped NetScript seams: the @netscript/fresh/ai durable-chat plane (published on JSR in @netscript/fresh and usable now, including the ai/sandbox MCP-UI subpath), the @netscript/fresh-ui copy-registry chat components, and the @netscript/ai MCP client stack.

What you will build

A chat-app/ Fresh workspace whose home screen is a working chat. The reader scaffolds a fresh NetScript project with the streams runtime, wires a durable chat session route that calls a model directly on @tanstack/ai, copies the fresh-ui ai component collection and hydrates a chat island, adds one server-side tool whose result surfaces as a tool-call card with citation chips, connects the chat to a remote MCP server and renders the ui:// widgets its tools return, and finally turns the island live so replies stream in as they arrive. This is a learning track: the same project grows chapter by chapter, so do them in order.

Before you begin

You need the standard NetScript toolchain — Deno, the Aspire CLI, and Docker — plus a model provider key. Confirm the toolchain:

deno --version && aspire --version && docker info

You should see a Deno 2.x version, an Aspire CLI version, and Docker engine details. If any are missing, the quickstart walks through installing them. Install the NetScript CLI once:

deno install --global --allow-all --name netscript jsr:@netscript/cli@0.0.6

The arc: route → UI → tools → MCP → live streaming

Each chapter adds exactly one link in the durable-chat spine:

1 · Scaffold the workspace

Create chat-app/ with netscript init, add the streams plugin so durable sessions have a runtime, set ANTHROPIC_API_KEY, and boot under Aspire.

2 · The durable chat route

Wire the session route with toNetScriptChatResponse + a required authorize hook, the one createNetScriptChatStreamProxy, and a direct model call on @tanstack/ai.

3 · The chat UI

Copy the fresh-ui ai collection (message, prompt-input, markdown, chat-render) and hydrate an island that seeds from resolveChatSnapshot and drives createNetScriptChatConnection.

4 · A server-side tool call

Add one @tanstack/ai tool the model can call; surface the invocation as a tool-call-card and render its citations as chips.

5 · MCP tools & widgets

Connect a remote MCP server with createMcpTransportPool from @netscript/ai/mcp, bridge its tools into the chat turn, and render ui:// widgets sandboxed through createMcpSandboxHandler and the copied McpUiWidget.

6 · Live streaming

Upgrade the island from settle-then-render to a live connection.subscribe(signal) read, folding each chunk through the one projection so replies stream in as they arrive, across tabs.

What you built

By the end of this track you own a working durable chat app and understand the seams that make it durable — the session route, the stream proxy, the SSR seed, and the client connection's send and live-subscribe sides — plus how the fresh-ui chat components render its transcript, how a tool call (yours or a remote MCP server's) lands as a durable card, and how MCP ui:// widgets render themed and sandboxed inside the chat.

After this track, keep building in Build › AI & Agents — the guides and recipes there pick up where these chapters stop.