experimental-ash 0.62.0 → 0.63.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # experimental-ash
 
+## 0.63.0
+
+### Minor Changes
+
+- 524cae7: Add `createWebSocketUpgradeServer()` as an escape hatch for `WS()` routes that need to adapt SDKs or frameworks which bind directly to Node `http.Server` upgrade events.
+- a491826: Add Svelte 5 and SvelteKit integrations, including a `useAshAgent` binding, a SvelteKit Vite plugin for Ash route proxying, Vercel services configuration, docs, tests, and an example app.
+- a491826: Add Vue composable (`useAshAgent`) and Nuxt module (`experimental-ash/nuxt`) for building agent UIs with Vue and Nuxt. The shared `AshAgentStore` class is now exported from `experimental-ash/client` for framework-agnostic consumption.
+
+## 0.62.1
+
+### Patch Changes
+
+- d141e9e: Update `@workflow/*` dependencies to the latest beta: `@workflow/core` 5.0.0-beta.12, `@workflow/errors` 5.0.0-beta.7, `@workflow/world` 5.0.0-beta.7, and `@workflow/world-local` 5.0.0-beta.13.
+
 ## 0.62.0
 
 ### Minor Changes

package/dist/docs/public/advanced/hooks.mdx

@@ -6,8 +6,10 @@ url: /hooks
 
 Hooks are Ash's authored extension points for the runtime event stream.
 
-This page is about `agent/hooks/*.ts` runtime hooks. For the React client hook,
-see [`useAshAgent`](../frontend/use-ash-agent.md).
+This page is about `agent/hooks/*.ts` runtime hooks. For the client-side hook,
+see [`useAshAgent`](../frontend/use-ash-agent.md) (React) or
+[`useAshAgent` (Vue)](../frontend/use-ash-agent-vue.md) or
+[`useAshAgent` (Svelte)](../frontend/use-ash-agent-svelte.md).
 
 Use a hook when you want to observe stream events (audit, metrics,
 alerting) without writing a tool, a context provider, or a channel
@@ -188,7 +190,11 @@ when both are registered.
 ## What to read next
 
 - [`useAshAgent`](../frontend/use-ash-agent.md)
+- [`useAshAgent` (Vue)](../frontend/use-ash-agent-vue.md)
+- [`useAshAgent` (Svelte)](../frontend/use-ash-agent-svelte.md)
 - [Next.js](../frontend/nextjs.md)
+- [Nuxt](../frontend/nuxt.md)
+- [SvelteKit](../frontend/sveltekit.md)
 - [Tools](./tools.mdx)
 - [Context Control](./context-control.md)
 - [Sessions And Streaming](./runs-and-streaming.md)

package/dist/docs/public/advanced/runs-and-streaming.md

@@ -13,9 +13,10 @@ The key client model is:
 - `POST /ash/v1/session/:sessionId` sends a follow-up message
 - `GET /ash/v1/session/:sessionId/stream` lets you watch the session in real time
 
-React apps can use [`useAshAgent()`](../frontend/use-ash-agent.md) instead of calling these
-routes directly. Next.js apps can use [`withAsh()`](../frontend/nextjs.md) to proxy these
-routes to the Ash runtime from the same origin.
+React apps can use [`useAshAgent()`](../frontend/use-ash-agent.md) and Vue apps can use
+[`useAshAgent()` (Vue)](../frontend/use-ash-agent-vue.md) instead of calling these routes
+directly. [Next.js](../frontend/nextjs.md) and [Nuxt](../frontend/nuxt.md) apps can proxy
+these routes to the Ash runtime from the same origin.
 
 Ash keeps those separate on purpose:
 
@@ -127,7 +128,9 @@ channel has already updated its state and the projection is current.
 ## What To Read Next
 
 - [`useAshAgent`](../frontend/use-ash-agent.md)
+- [`useAshAgent` (Vue)](../frontend/use-ash-agent-vue.md)
 - [Next.js](../frontend/nextjs.md)
+- [Nuxt](../frontend/nuxt.md)
 - [Session Context](./session-context.md)
 - [Subagents](./subagents.mdx)
 - [Schedules](./schedules.mdx)

package/dist/docs/public/advanced/typescript-api.md

@@ -18,6 +18,10 @@ Source of truth:
 - React subpath: [`../../packages/ash/src/react/index.ts`](../../packages/ash/src/react/index.ts)
 - client subpath: [`../../packages/ash/src/client/index.ts`](../../packages/ash/src/client/index.ts)
 - evals subpath: [`../../packages/ash/src/evals/index.ts`](../../packages/ash/src/evals/index.ts)
+- vue subpath: [`../../packages/ash/src/vue/index.ts`](../../packages/ash/src/vue/index.ts)
+- nuxt subpath: [`../../packages/ash/src/public/nuxt/index.ts`](../../packages/ash/src/public/nuxt/index.ts)
+- svelte subpath: [`../../packages/ash/src/svelte/index.ts`](../../packages/ash/src/svelte/index.ts)
+- SvelteKit subpath: [`../../packages/ash/src/public/sveltekit/index.ts`](../../packages/ash/src/public/sveltekit/index.ts)
 
 ## Definition Helpers
 
@@ -85,6 +89,32 @@ React helpers exported from `experimental-ash/react`:
 - `UseAshAgentOptions`, `UseAshAgentHelpers`, `UseAshAgentSnapshot`, `UseAshAgentStatus` - hook configuration and state types
 - `AshMessageData`, `AshMessage`, `AshMessagePart`, `AshDynamicToolPart` - default message projection types
 
+Nuxt helpers exported from `experimental-ash/nuxt`:
+
+- `default` - the Nuxt module that runs the Ash agent alongside your Nuxt app
+- `ASH_NUXT_SERVICE_PREFIX` - default private Vercel service prefix for the Ash service
+- `AshNuxtModuleOptions` - options for `ashRoot`, `ashBuildCommand`, `configureVercelJson`, and `servicePrefix`
+
+Vue helpers exported from `experimental-ash/vue`:
+
+- `useAshAgent(options?)` - Vue composable for sending turns, streaming events, projecting reactive UI state, and tracking a session cursor
+- `defaultMessageReducer()` - default chat-style event projection used by `useAshAgent()`
+- `UseAshAgentOptions`, `UseAshAgentReturn`, `UseAshAgentSnapshot`, `UseAshAgentStatus`, `PrepareSend` - composable configuration and state types
+- `AshAgentReducer`, `AshMessageData`, `AshMessage`, `AshMessagePart`, `AshDynamicToolPart` - reducer and default message projection types
+
+SvelteKit helpers exported from `experimental-ash/sveltekit`:
+
+- `ashSvelteKit(options?)` - Vite plugin that runs the Ash agent alongside your SvelteKit app
+- `ASH_SVELTEKIT_SERVICE_PREFIX` - default private Vercel service prefix for the Ash service
+- `AshSvelteKitPluginOptions` - options for `ashRoot`, `ashBuildCommand`, `configureVercelJson`, and `servicePrefix`
+
+Svelte helpers exported from `experimental-ash/svelte`:
+
+- `useAshAgent(options?)` - Svelte 5 binding for sending turns, streaming events, projecting rune-friendly UI state, and tracking a session cursor
+- `defaultMessageReducer()` - default chat-style event projection used by `useAshAgent()`
+- `UseAshAgentOptions`, `UseAshAgentReturn`, `UseAshAgentSnapshot`, `UseAshAgentStatus`, `PrepareSend` - binding configuration and state types
+- `AshAgentReducer`, `AshMessageData`, `AshMessage`, `AshMessagePart`, `AshDynamicToolPart` - reducer and default message projection types
+
 Client helpers exported from `experimental-ash/client`:
 
 - `Client` - HTTP client for an Ash server
@@ -321,6 +351,8 @@ import { Braintrust } from "experimental-ash/evals/reporters";
 - `ctx.session` -> [Session Context](./session-context.md)
 - `withAsh` -> [Next.js](../frontend/nextjs.md)
 - `useAshAgent` -> [`useAshAgent`](../frontend/use-ash-agent.md)
+- `useAshAgent` (Vue) and `defaultMessageReducer` -> [`useAshAgent` (Vue)](../frontend/use-ash-agent-vue.md)
+- Nuxt module (`experimental-ash/nuxt`) -> [Nuxt](../frontend/nuxt.md)
 - subagents (authored with `defineAgent` under `subagents/<id>/agent.ts`) -> [Subagents](./subagents.mdx)
 - `defineSchedule` -> [Schedules](./schedules.mdx)
 - `defineEvalSuite`, loaders, reporters, and scorers -> [Evals](./evals.mdx)

package/dist/docs/public/channels/custom.mdx

@@ -89,6 +89,29 @@ export default defineChannel({
 `params`, `waitUntil`, and `requestIp`. The returned hooks are Ash-owned structural types compatible
 with Nitro/H3 websocket routing, including `upgrade`, `open`, `message`, `close`, and `error`.
 
+### Node upgrade server escape hatch
+
+Prefer the `WS()` lifecycle hooks above when you own the websocket behavior. Ash also exposes
+`createWebSocketUpgradeServer()` for the narrower case where a third-party SDK or framework expects
+to bind directly to a Node `http.Server` with `server.on("upgrade", ...)`.
+
+```ts
+import { defineChannel, WS, createWebSocketUpgradeServer } from "experimental-ash/channels";
+
+const bridge = createWebSocketUpgradeServer();
+
+thirdPartySdk.attach(bridge.server);
+
+export default defineChannel({
+  routes: [WS("/vendor/ws", bridge.route)],
+});
+```
+
+The bridge server does not listen on its own port. It receives only upgrade events that matched the
+Ash route, and only on hosts where Nitro exposes the raw Node upgrade request, socket, and head. Treat
+it as a compatibility adapter for libraries with server-binding APIs, not as the primary way to build
+websocket channels in Ash.
+
 ## Cross-channel hand-off
 
 Route handlers can start a session on a different channel via `args.receive(channel, ...)`. Use this

package/dist/docs/public/frontend/README.md

@@ -4,13 +4,17 @@ description: "Wire your web app to an Ash agent."
 url: /frontend
 ---
 
-Ash ships first-class helpers for the two most common ways to put an agent
+Ash ships first-class helpers for the most common ways to put an agent
 behind a web UI:
 
 - [Next.js](./nextjs.md) — `withAsh()` runs the Ash agent alongside your
   Next.js app.
-- [`useAshAgent`](./use-ash-agent.md) — React hook for chat and agent UIs in any
-  React app.
+- [Nuxt](./nuxt.md) — `experimental-ash/nuxt` module runs the Ash agent
+  alongside your Nuxt app.
+- [`useAshAgent` (React)](./use-ash-agent.md) — React hook for chat and agent
+  UIs in any React app.
+- [`useAshAgent` (Vue)](./use-ash-agent-vue.md) — Vue composable for chat and
+  agent UIs in any Vue app.
 
 For other stacks, call Ash directly over its HTTP routes —
-see [Sessions And Streaming](../runs-and-streaming.md).
+see [Sessions And Streaming](../advanced/runs-and-streaming.md).

package/dist/docs/public/frontend/meta.json

@@ -1,3 +1,11 @@
 {
-  "pages": ["README", "nextjs", "use-ash-agent"]
+  "pages": [
+    "README",
+    "nextjs",
+    "nuxt",
+    "sveltekit",
+    "use-ash-agent",
+    "use-ash-agent-vue",
+    "use-ash-agent-svelte"
+  ]
 }

package/dist/docs/public/frontend/nextjs.md

@@ -198,11 +198,11 @@ next call only). See [`useAshAgent`](./use-ash-agent.md#add-per-turn-client-cont
 for the full pattern.
 
 For server-side enrichment (policy, durable context, dynamic skills), use
-runtime lifecycle hooks instead. See [Hooks](../hooks.md).
+runtime lifecycle hooks instead. See [Hooks](../advanced/hooks.mdx).
 
 ## What To Read Next
 
 - [`useAshAgent`](./use-ash-agent.md)
-- [Auth And Route Protection](../auth-and-route-protection.md)
-- [Hooks](../hooks.md)
-- [Sessions And Streaming](../runs-and-streaming.md)
+- [Auth And Route Protection](../advanced/auth-and-route-protection.mdx)
+- [Hooks](../advanced/hooks.mdx)
+- [Sessions And Streaming](../advanced/runs-and-streaming.md)

package/dist/docs/public/frontend/nuxt.md

@@ -0,0 +1,168 @@
+---
+title: "Nuxt"
+description: "Add an Ash agent to a Nuxt app and call it from the browser."
+---
+
+`experimental-ash/nuxt` lets you ship a Nuxt frontend and an Ash agent as
+one project. Come in from either side: drop it into an existing Nuxt app
+to add an agent, or start with an agent and point a Nuxt project at it.
+
+- **One dev server.** `nuxt dev` runs the app and the agent together.
+- **One deploy.** Vercel ships them as a single project; no extra service to operate.
+- **Zero URL plumbing.** `useAshAgent()` finds the mounted routes automatically; no CORS, no env vars.
+
+## Add Ash To Nuxt
+
+Register the module in your Nuxt config:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ["experimental-ash/nuxt"],
+});
+```
+
+By default, the module looks for an `agent/` folder inside your Nuxt
+project root. Pass `ashRoot` when the agent lives somewhere else:
+
+```ts
+export default defineNuxtConfig({
+  modules: ["experimental-ash/nuxt"],
+  ash: {
+    ashRoot: "../my-agent",
+  },
+});
+```
+
+## Add The Ash Channel
+
+Skip this section if the framework default channel works for you. The module
+already wires Ash up without it.
+
+Create `agent/channels/ash.ts` when you want to choose the route auth policy
+explicitly:
+
+```ts
+// agent/channels/ash.ts
+import { ashChannel } from "experimental-ash/channels/ash";
+import { none } from "experimental-ash/channels/auth";
+
+export default ashChannel({
+  auth: none(),
+});
+```
+
+For protected apps, replace `none()` with a channel auth helper such as
+`vercelOidc()`, `oidc(...)`, or `httpBasic(...)`.
+
+## Use The Vue Composable
+
+Once the module is in `nuxt.config.ts`, browser code can use
+[`useAshAgent()`](./use-ash-agent-vue.md) without a custom host. The module
+auto-imports the composable, so no explicit import is needed:
+
+```vue
+<script setup lang="ts">
+const { status, sendMessage } = useAshAgent();
+
+const isBusy = computed(() => status.value === "submitted" || status.value === "streaming");
+
+const message = ref("");
+
+async function handleSubmit() {
+  const text = message.value.trim();
+  if (!text || isBusy.value) return;
+  message.value = "";
+  await sendMessage(text);
+}
+</script>
+
+<template>
+  <form @submit.prevent="handleSubmit">
+    <input v-model="message" :disabled="isBusy" />
+    <button type="submit" :disabled="isBusy">Send</button>
+  </form>
+</template>
+```
+
+The composable handles conversation state, streaming updates, errors, and
+messages for you. See [`useAshAgent` (Vue)](./use-ash-agent-vue.md) for the
+full API.
+
+## Local Development
+
+`pnpm dev` is enough. The module boots the Ash dev server alongside Nuxt
+and proxies the Ash routes to it, so your browser keeps talking to the
+Nuxt origin.
+
+## Vercel Deployments
+
+On Vercel, the module keeps the web app public and the Ash runtime tucked
+behind it. Users visit the Nuxt app, and the browser talks to the agent
+through the same site origin.
+
+Use `ashBuildCommand` when the agent needs a project-specific build command:
+
+```ts
+export default defineNuxtConfig({
+  modules: ["experimental-ash/nuxt"],
+  ash: {
+    ashBuildCommand: "pnpm build:ash",
+  },
+});
+```
+
+## Non-Vercel Production Hosts
+
+If you deploy somewhere other than Vercel and the Ash service runs on a
+separate origin, point Nuxt at it with `ASH_NUXT_PRODUCTION_ORIGIN`:
+
+```bash
+ASH_NUXT_PRODUCTION_ORIGIN=https://agent.example.com pnpm build
+```
+
+Set `ASH_NUXT_PRODUCTION_PORT` to use a different local port (default `4274`):
+
+```bash
+ASH_NUXT_PRODUCTION_PORT=5000 pnpm build && pnpm preview
+```
+
+## Authenticated Requests
+
+Because the agent runs on the same origin as your Nuxt app, the auth you
+already use for the rest of the app applies to it for free. Cookie-based
+sessions work without extra wiring: the browser already sends those cookies
+on every Ash request.
+
+For non-cookie schemes (bearer tokens, custom headers), attach them from the
+client instead:
+
+```vue
+<script setup lang="ts">
+const agent = useAshAgent({
+  headers: async () => ({
+    authorization: `Bearer ${await getAccessToken()}`,
+  }),
+});
+</script>
+```
+
+Prefer function values for short-lived credentials. Ash re-resolves them
+before each HTTP request, including reconnects.
+
+## Add Per-Turn Page Context
+
+`useAshAgent()` accepts a `prepareSend` callback for attaching one-turn page
+state (pathname, selected ids, anything else the model should see for the
+next call only). See [`useAshAgent` (Vue)](./use-ash-agent-vue.md#add-per-turn-client-context)
+for the full pattern.
+
+For server-side enrichment (policy, durable context, dynamic skills), use
+runtime lifecycle hooks instead. See [Hooks](../advanced/hooks.mdx).
+
+## What To Read Next
+
+- [`useAshAgent` (Vue)](./use-ash-agent-vue.md)
+- [Auth And Route Protection](../advanced/auth-and-route-protection.mdx)
+- [Hooks](../advanced/hooks.mdx)
+- [Sessions And Streaming](../advanced/runs-and-streaming.md)

package/dist/docs/public/frontend/sveltekit.md

@@ -0,0 +1,177 @@
+---
+title: "SvelteKit"
+description: "Add an Ash agent to a SvelteKit app and call it from the browser."
+---
+
+`experimental-ash/sveltekit` lets you ship a SvelteKit frontend and an Ash
+agent as one project. Add the Vite plugin to an existing SvelteKit app, or
+start with an agent and point a SvelteKit project at it.
+
+- **One dev server.** `vite dev` runs the app and the agent together.
+- **One deploy.** Vercel ships them as a single project; no extra service to operate.
+- **Zero URL plumbing.** `useAshAgent()` finds the mounted routes automatically; no CORS, no env vars.
+
+## Add Ash To SvelteKit
+
+Register the plugin in your Vite config:
+
+```ts
+// vite.config.ts
+import { sveltekit } from "@sveltejs/kit/vite";
+import { ashSvelteKit } from "experimental-ash/sveltekit";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [ashSvelteKit(), sveltekit()],
+});
+```
+
+By default, the plugin looks for an `agent/` folder inside your SvelteKit
+project root. Pass `ashRoot` when the agent lives somewhere else:
+
+```ts
+export default defineConfig({
+  plugins: [
+    ashSvelteKit({
+      ashRoot: "../my-agent",
+    }),
+    sveltekit(),
+  ],
+});
+```
+
+## Add The Ash Channel
+
+Skip this section if the framework default channel works for you. The plugin
+already wires Ash up without it.
+
+Create `agent/channels/ash.ts` when you want to choose the route auth policy
+explicitly:
+
+```ts
+// agent/channels/ash.ts
+import { ashChannel } from "experimental-ash/channels/ash";
+import { none } from "experimental-ash/channels/auth";
+
+export default ashChannel({
+  auth: none(),
+});
+```
+
+For protected apps, replace `none()` with a channel auth helper such as
+`vercelOidc()`, `oidc(...)`, or `httpBasic(...)`.
+
+## Use The Svelte Binding
+
+Once the plugin is in `vite.config.ts`, browser code can use
+[`useAshAgent()`](./use-ash-agent-svelte.md) without a custom host:
+
+```svelte
+<script lang="ts">
+  import { useAshAgent } from "experimental-ash/svelte";
+
+  const agent = useAshAgent();
+  let message = $state("");
+  let isBusy = $derived(agent.status === "submitted" || agent.status === "streaming");
+
+  async function handleSubmit() {
+    const text = message.trim();
+    if (!text || isBusy) return;
+    message = "";
+    await agent.sendMessage(text);
+  }
+</script>
+
+<form onsubmit={(event) => {
+  event.preventDefault();
+  void handleSubmit();
+}}>
+  <input bind:value={message} disabled={isBusy} />
+  <button type="submit" disabled={isBusy}>Send</button>
+</form>
+```
+
+The binding handles conversation state, streaming updates, errors, and messages
+for you. See [`useAshAgent` (Svelte)](./use-ash-agent-svelte.md) for the full
+API.
+
+## Local Development
+
+`pnpm dev` is enough. The plugin boots the Ash dev server alongside SvelteKit
+and proxies the Ash routes to it, so your browser keeps talking to the
+SvelteKit origin.
+
+`pnpm build && pnpm preview` works the same way for local production preview:
+the preview server gets its own Ash route proxy and reuses or starts the shared
+Ash server automatically.
+
+## Vercel Deployments
+
+On Vercel, the plugin keeps the web app public and the Ash runtime tucked
+behind it. Users visit the SvelteKit app, and the browser talks to the agent
+through the same site origin.
+
+Use `ashBuildCommand` when the agent needs a project-specific build command:
+
+```ts
+export default defineConfig({
+  plugins: [
+    ashSvelteKit({
+      ashBuildCommand: "pnpm build:ash",
+    }),
+    sveltekit(),
+  ],
+});
+```
+
+## Non-Vercel Production Hosts
+
+If you deploy somewhere other than Vercel and the Ash service runs on a
+separate origin, pass `host` directly to `useAshAgent`:
+
+```ts
+const agent = useAshAgent({
+  host: "https://agent.example.com",
+});
+```
+
+## Authenticated Requests
+
+Because the agent runs on the same origin as your SvelteKit app, the auth you
+already use for the rest of the app applies to it for free. Cookie-based
+sessions work without extra wiring: the browser already sends those cookies on
+every Ash request.
+
+For non-cookie schemes (bearer tokens, custom headers), attach them from the
+client instead:
+
+```svelte
+<script lang="ts">
+  const agent = useAshAgent({
+    headers: async () => ({
+      authorization: `Bearer ${await getAccessToken()}`,
+    }),
+  });
+</script>
+```
+
+Prefer function values for short-lived credentials. Ash re-resolves them before
+each HTTP request, including reconnects.
+
+## Add Per-Turn Page Context
+
+`useAshAgent()` accepts a `prepareSend` callback for attaching one-turn page
+state (pathname, selected ids, anything else the model should see for the next
+call only). See
+[`useAshAgent` (Svelte)](./use-ash-agent-svelte.md#add-per-turn-client-context)
+for the full pattern.
+
+For server-side enrichment (policy, durable context, dynamic skills), use
+runtime lifecycle hooks instead. See [Hooks](../advanced/hooks.mdx).
+
+## What To Read Next
+
+- [`useAshAgent` (Svelte)](./use-ash-agent-svelte.md)
+- [Auth And Route Protection](../advanced/auth-and-route-protection.mdx)
+- [Hooks](../advanced/hooks.mdx)
+- [Sessions And Streaming](../advanced/runs-and-streaming.md)