feat(ai-harness): build a harness into a worker artifact, and run it as a worker

.changeset/harness-build-worker.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-harness': minor
+---
+
+`@tanstack/ai-harness/build` and `@tanstack/ai-harness/worker`: `buildHarness` bundles a harness with Bun into a worker artifact (`harness.js` and a `harness.manifest.json` with the sha256 digest), and can also build a single executable. `artifactText(dir)` checks the digest and uses the artifact as the model of a `chat()` call, with one worker process per thread. `runHarnessWorker` runs a harness on stdin and stdout with the session frames of the harness protocol.

docs/config.json

@@ -941,6 +941,11 @@
           "addedAt": "2026-10-13",
           "updatedAt": "2026-10-14"
         },
+        {
+          "label": "Deploy a harness",
+          "to": "harness/deploy",
+          "addedAt": "2026-10-13"
+        },
         {
           "label": "Send inputs safely",
           "to": "harness/inputs",

docs/harness/deploy.md

@@ -0,0 +1,93 @@
+---
+title: Deploy a harness
+id: harness-deploy
+order: 6
+description: "Run a harness in your server, as a worker process, on another machine, or as a single executable."
+keywords:
+  - tanstack ai
+  - harness
+  - deploy
+  - build
+  - worker
+---
+
+Your harness works on your laptop. Now it needs to run next to your API, in its own process, on a different machine, or as a CLI your team can download. You pick the place. The harness definition stays the same.
+
+| Place | How |
+|---|---|
+| Your server | `createHarnessHost` and `createHarnessHandler` in your routes. No build step. |
+| A worker process | `buildHarness`, then `artifactText(dir)` as the model of a `chat()` call. |
+| Another machine | `createHarnessHandler` there, then `harnessText({ url, token })` here. |
+| A single executable | `buildHarness({ compile })` with Bun. |
+
+## Build a worker artifact
+
+`buildHarness` bundles the harness with Bun and writes a manifest next to it. Install [Bun](https://bun.sh) on the build machine.
+
+```ts group=harness-deploy
+import { artifactText, buildHarness } from '@tanstack/ai-harness/build'
+
+const { manifest } = await buildHarness({
+  entry: './src/studio.ts',
+  export: 'studio',
+  outDir: './dist/studio',
+})
+console.log(manifest.name, manifest.digest)
+```
+
+- `dist/studio/harness.js` starts the harness as a worker. It reads session frames on stdin and writes them on stdout.
+- `dist/studio/harness.manifest.json` names the harness, its agents and plugins, what it needs (file system, processes, network), and the sha256 digest of the bundle.
+
+The build imports your entry in a child process to read the harness name, agents, and plugins. Importing a module runs its code.
+
+## Run the artifact as a model
+
+`artifactText` starts one worker process per outer thread and checks the digest first. A changed bundle is refused.
+
+```ts group=harness-deploy
+import { chat } from '@tanstack/ai'
+
+const model = await artifactText('./dist/studio')
+const stream = chat({
+  adapter: model,
+  messages: [{ role: 'user', content: 'Plan the launch post.' }],
+  threadId: 'thread-1',
+})
+// When you are done with the workers:
+model.dispose()
+```
+
+The worker keeps the conversation of its thread between calls. Workers get the environment of the process that starts them, so they can read your provider keys.
+
+## Use a harness on another machine
+
+On the other machine, serve the harness with `createHarnessHandler`, and check a bearer token in `authorize`. See [Serve the session over HTTP](./connect#serve-the-session-over-http).
+
+Here, use it as a model:
+
+```ts group=harness-deploy
+import { harnessText } from '@tanstack/ai-harness'
+
+const remote = harnessText({ url: 'http://build-box:8787', token: 'your-token' })
+```
+
+The remote session keeps the conversation, so each call sends only the new message.
+
+## Ship a single executable
+
+Point `compile.entry` at the file that starts your app, for example a server or a command-line tool that imports the harness:
+
+```ts group=harness-deploy
+await buildHarness({
+  entry: './src/studio.ts',
+  export: 'studio',
+  outDir: './dist/studio',
+  compile: { entry: './src/main.ts', outfile: './dist/studio-app', target: 'bun-linux-x64' },
+})
+```
+
+Bun can build for another platform with `target`, for example `bun-darwin-arm64` or `bun-windows-x64`.
+
+## What you have now
+
+- The same harness in your server, in a worker process, on another machine, or as a binary.

packages/ai-harness/package.json

@@ -34,6 +34,14 @@
       "types": "./dist/esm/client.d.ts",
       "import": "./dist/esm/client.js"
     },
+    "./build": {
+      "types": "./dist/esm/build.d.ts",
+      "import": "./dist/esm/build.js"
+    },
+    "./worker": {
+      "types": "./dist/esm/worker.d.ts",
+      "import": "./dist/esm/worker.js"
+    },
     "./view": {
       "types": "./dist/esm/view/index.d.ts",
       "import": "./dist/esm/view/index.js"