experimental-ash 0.62.0 → 0.64.0

package/dist/docs/public/frontend/use-ash-agent-svelte.md

@@ -0,0 +1,185 @@
+---
+title: "useAshAgent (Svelte)"
+description: "Svelte 5 binding that drives an Ash agent session from the browser."
+---
+
+`useAshAgent()` is a Svelte 5 binding that opens a long-lived Ash session in
+the browser, lets the user send turns, and projects every stream event into
+rune-friendly reactive data for your template.
+
+The simplest usage:
+
+```svelte
+<script lang="ts">
+  import { useAshAgent } from "experimental-ash/svelte";
+
+  const agent = useAshAgent();
+</script>
+
+{#each agent.data.messages as message}
+  <p>{message.role}: {JSON.stringify(message.parts)}</p>
+{/each}
+```
+
+## What It Returns
+
+`useAshAgent()` returns an object with reactive properties and action methods:
+
+| Property      | Type                                   | Description                                                                                                                                                |
+| ------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data`        | `TData`                                | Projected state built by reducing every stream event through the reducer. With the default reducer this is `AshMessageData` containing a `messages` array. |
+| `status`      | `UseAshAgentStatus`                    | `"ready"`, `"submitted"`, `"streaming"`, or `"error"`                                                                                                      |
+| `error`       | `Error \| undefined`                   | Last transport-level error                                                                                                                                 |
+| `events`      | `readonly HandleMessageStreamEvent[]`  | Raw server events for this session                                                                                                                         |
+| `session`     | `SessionState`                         | Snapshot of session state                                                                                                                                  |
+| `send`        | `(input, options?) => Promise<void>`   | Send a turn with full options                                                                                                                              |
+| `sendMessage` | `(message, options?) => Promise<void>` | Shorthand: send a plain text turn                                                                                                                          |
+| `stop`        | `() => void`                           | Abort the in-flight request                                                                                                                                |
+| `reset`       | `() => void`                           | Clear state and start a new session                                                                                                                        |
+
+The state fields are reactive getters. Read them directly from templates,
+`$derived`, or `$effect`; do not prefix them with `$` like Svelte stores.
+
+## Send A Message
+
+```svelte
+<script lang="ts">
+  import { useAshAgent } from "experimental-ash/svelte";
+
+  const agent = useAshAgent();
+  let message = $state("");
+
+  async function handleSubmit() {
+    const text = message.trim();
+    if (!text) return;
+    message = "";
+    await agent.sendMessage(text);
+  }
+</script>
+
+<form onsubmit={(event) => {
+  event.preventDefault();
+  void handleSubmit();
+}}>
+  <input bind:value={message} placeholder="Type a message..." />
+  <button type="submit">Send</button>
+</form>
+```
+
+## Send Attachments
+
+Use `send()` for structured input. Attachments use the AI SDK `UserContent`
+format:
+
+```ts
+await agent.send({
+  message: [
+    { type: "text", text: "Describe this image." },
+    { type: "file", data: fileBytes, mimeType: "image/png" },
+  ],
+});
+```
+
+## Respond To Human-In-The-Loop Prompts
+
+When the agent requests human input (tool approvals, confirmations), the
+`inputRequest` shows up inside `message.parts` on `dynamic-tool` parts. Send
+`inputResponses` back:
+
+```ts
+await agent.send({
+  inputResponses: [{ requestId: inputRequest.requestId, optionId: "approve" }],
+});
+```
+
+## Stop And Reset
+
+```ts
+agent.stop(); // abort the in-flight stream
+agent.reset(); // wipe state and create a new session
+```
+
+## Resumable Sessions
+
+Pass `initialSession` to restore a session from a prior page load:
+
+```ts
+const agent = useAshAgent({
+  initialSession: savedSessionState,
+  initialEvents: savedEvents,
+});
+```
+
+## Add Per-Turn Client Context
+
+Use `prepareSend` to attach short-lived page state to each turn:
+
+```ts
+const agent = useAshAgent({
+  prepareSend(input) {
+    return {
+      ...input,
+      clientContext: {
+        pathname: window.location.pathname,
+      },
+    };
+  },
+});
+```
+
+## Custom Host And Auth
+
+Use `host` for non-standard routing, and `auth` or `headers` for credentials:
+
+```ts
+const agent = useAshAgent({
+  host: "https://agent.example.com",
+  headers: async () => ({
+    authorization: `Bearer ${await getAccessToken()}`,
+  }),
+});
+```
+
+## Custom Reducer
+
+Pass a custom `reducer` to control how stream events project into `data`:
+
+```ts
+import { useAshAgent, type AshAgentReducer } from "experimental-ash/svelte";
+
+interface MyData {
+  turns: number;
+}
+
+const reducer: AshAgentReducer<MyData> = {
+  initial: () => ({ turns: 0 }),
+  reduce: (data, event) => {
+    if (event.type === "turn.completed") {
+      return { turns: data.turns + 1 };
+    }
+    return data;
+  },
+};
+
+const agent = useAshAgent({ reducer });
+// agent.data is MyData
+```
+
+## Lifecycle Callbacks
+
+```ts
+const agent = useAshAgent({
+  onError: (error) => console.error(error),
+  onEvent: (event) => console.log(event.type),
+  onFinish: (snapshot) => console.log("done", snapshot.status),
+  onSessionChange: (session) => {
+    localStorage.setItem("ash-session", JSON.stringify(session));
+  },
+});
+```
+
+## What To Read Next
+
+- [SvelteKit](./sveltekit.md) - framework setup
+- [Sessions And Streaming](../advanced/runs-and-streaming.md) - under the hood
+- [TypeScript API](../advanced/typescript-api.md) - client exports

package/dist/docs/public/frontend/use-ash-agent-vue.md

@@ -0,0 +1,236 @@
+---
+title: "useAshAgent (Vue)"
+description: "Vue composable that drives an Ash agent session from the browser."
+---
+
+`useAshAgent()` is a Vue composable that opens a long-lived Ash session
+in the browser, lets the user send turns, and projects every stream event
+into reactive data for your template.
+
+The simplest usage:
+
+```vue
+<script setup lang="ts">
+import { useAshAgent } from "experimental-ash/vue";
+
+const { data } = useAshAgent();
+</script>
+
+<template>
+  <div v-for="message in data.messages" :key="message.id">
+    <p>{{ message.role }}: {{ message.parts }}</p>
+  </div>
+</template>
+```
+
+## What It Returns
+
+`useAshAgent()` returns an object of computed refs and action methods:
+
+| Property      | Type                                               | Description                                                                                                                                                |
+| ------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data`        | `ComputedRef<TData>`                               | Projected state built by reducing every stream event through the reducer. With the default reducer this is `AshMessageData` containing a `messages` array. |
+| `status`      | `ComputedRef<UseAshAgentStatus>`                   | `"ready"`, `"submitted"`, `"streaming"`, or `"error"`                                                                                                      |
+| `error`       | `ComputedRef<Error \| undefined>`                  | Last transport-level error                                                                                                                                 |
+| `events`      | `ComputedRef<readonly HandleMessageStreamEvent[]>` | Raw server events for this session                                                                                                                         |
+| `session`     | `ComputedRef<SessionState>`                        | Snapshot of session state                                                                                                                                  |
+| `send`        | `(input, options?) => Promise<void>`               | Send a turn with full options                                                                                                                              |
+| `sendMessage` | `(message, options?) => Promise<void>`             | Shorthand: send a plain text turn                                                                                                                          |
+| `stop`        | `() => void`                                       | Abort the in-flight request                                                                                                                                |
+| `reset`       | `() => void`                                       | Clear state and start a new session                                                                                                                        |
+
+The state properties (`data`, `status`, `error`, `events`, `session`) are
+`ComputedRef`s; the rest are methods. Destructure whatever you need — refs keep
+their reactivity through destructuring — and read them with `.value` in
+`<script>` or unwrapped (no `.value`) in `<template>`.
+
+## Send A Message
+
+```vue
+<script setup lang="ts">
+import { useAshAgent } from "experimental-ash/vue";
+
+const { sendMessage } = useAshAgent();
+const message = ref("");
+
+async function handleSubmit() {
+  const text = message.value.trim();
+  if (!text) return;
+  message.value = "";
+  await sendMessage(text);
+}
+</script>
+
+<template>
+  <form @submit.prevent="handleSubmit">
+    <input v-model="message" placeholder="Type a message..." />
+    <button type="submit">Send</button>
+  </form>
+</template>
+```
+
+## Send Attachments
+
+Use `send()` for structured input. Attachments use the AI SDK `UserContent`
+format:
+
+```vue
+<script setup lang="ts">
+import { useAshAgent } from "experimental-ash/vue";
+
+const { send } = useAshAgent();
+
+async function onFileChange(event: Event) {
+  const file = (event.target as HTMLInputElement).files?.[0];
+  if (!file) return;
+  await send({
+    message: [
+      { type: "text", text: "Describe this image." },
+      { type: "file", data: new Uint8Array(await file.arrayBuffer()), mediaType: file.type },
+    ],
+  });
+}
+</script>
+
+<template>
+  <input type="file" accept="image/*" @change="onFileChange" />
+</template>
+```
+
+## Respond To Human-In-The-Loop Prompts
+
+When the agent requests human input (tool approvals, confirmations),
+the `inputRequest` shows up inside `message.parts` on `dynamic-tool` parts.
+Send `inputResponses` back:
+
+```vue
+<script setup lang="ts">
+import { useAshAgent, type AshDynamicToolPart } from "experimental-ash/vue";
+
+const props = defineProps<{ part: AshDynamicToolPart }>();
+
+const { send } = useAshAgent();
+
+const inputRequest = computed(() => props.part.toolMetadata?.ash?.inputRequest);
+
+function respond(optionId: string) {
+  const request = inputRequest.value;
+  if (!request) return;
+  void send({ inputResponses: [{ requestId: request.requestId, optionId }] });
+}
+</script>
+
+<template>
+  <div v-if="inputRequest">
+    <p>{{ inputRequest.prompt }}</p>
+    <button v-for="option in inputRequest.options" :key="option.id" @click="respond(option.id)">
+      {{ option.label }}
+    </button>
+  </div>
+</template>
+```
+
+## Stop And Reset
+
+Abort the in-flight stream, or wipe state and start a fresh session:
+
+```vue
+<script setup lang="ts">
+import { useAshAgent } from "experimental-ash/vue";
+
+const { status, stop, reset } = useAshAgent();
+
+const isBusy = computed(() => status.value === "submitted" || status.value === "streaming");
+</script>
+
+<template>
+  <button :disabled="!isBusy" @click="stop()">Stop</button>
+  <button @click="reset()">Reset</button>
+</template>
+```
+
+## Resumable Sessions
+
+Pass `initialSession` to restore a session from a prior page load:
+
+```ts
+const agent = useAshAgent({
+  initialSession: savedSessionState,
+  initialEvents: savedEvents,
+});
+```
+
+## Add Per-Turn Client Context
+
+Use `prepareSend` to attach short-lived page state to each turn:
+
+```ts
+const agent = useAshAgent({
+  prepareSend(input) {
+    return {
+      ...input,
+      clientContext: {
+        pathname: window.location.pathname,
+      },
+    };
+  },
+});
+```
+
+## Custom Host And Auth
+
+Use `host` for non-standard routing, and `auth` or `headers` for
+credentials:
+
+```ts
+const agent = useAshAgent({
+  host: "https://agent.example.com",
+  headers: async () => ({
+    authorization: `Bearer ${await getAccessToken()}`,
+  }),
+});
+```
+
+## Custom Reducer
+
+Pass a custom `reducer` to control how stream events project into `data`:
+
+```ts
+import { useAshAgent, type AshAgentReducer } from "experimental-ash/vue";
+
+interface MyData {
+  turns: number;
+}
+
+const reducer: AshAgentReducer<MyData> = {
+  initial: () => ({ turns: 0 }),
+  reduce: (data, event) => {
+    if (event.type === "turn.completed") {
+      return { turns: data.turns + 1 };
+    }
+    return data;
+  },
+};
+
+const { data } = useAshAgent({ reducer });
+// data.value is MyData
+```
+
+## Lifecycle Callbacks
+
+```ts
+const agent = useAshAgent({
+  onError: (error) => console.error(error),
+  onEvent: (event) => console.log(event.type),
+  onFinish: (snapshot) => console.log("done", snapshot.status),
+  onSessionChange: (session) => {
+    localStorage.setItem("ash-session", JSON.stringify(session));
+  },
+});
+```
+
+## What To Read Next
+
+- [Nuxt](./nuxt.md) — module setup
+- [Sessions And Streaming](../advanced/runs-and-streaming.md) — under the hood
+- [TypeScript API](../advanced/typescript-api.md) — client exports

package/dist/docs/public/frontend/use-ash-agent.md

@@ -60,17 +60,17 @@ your component can call the agent without configuring a separate URL.
 
 `useAshAgent()` returns the current UI state plus commands:
 
-| Field         | What it is                                                                                       |
-| ------------- | ------------------------------------------------------------------------------------------------ |
-| `data`        | Projected UI state from the reducer. Defaults to `{ messages }`.                                 |
-| `status`      | `"ready"`, `"submitted"`, `"streaming"`, or `"error"`. Drives the composer.                      |
-| `error`       | The last `Error` thrown, if any.                                                                 |
-| `events`      | Raw Ash stream events for this session — see [Sessions And Streaming](../runs-and-streaming.md). |
-| `session`     | Serializable session cursor (`sessionId`, `continuationToken`, `streamIndex`).                   |
-| `sendMessage` | Send plain text.                                                                                 |
-| `send`        | Send the full turn payload (multi-part messages, HITL responses).                                |
-| `stop`        | Abort the active request.                                                                        |
-| `reset`       | Clear local events, data, errors, and the local session cursor.                                  |
+| Field         | What it is                                                                                                |
+| ------------- | --------------------------------------------------------------------------------------------------------- |
+| `data`        | Projected UI state from the reducer. Defaults to `{ messages }`.                                          |
+| `status`      | `"ready"`, `"submitted"`, `"streaming"`, or `"error"`. Drives the composer.                               |
+| `error`       | The last `Error` thrown, if any.                                                                          |
+| `events`      | Raw Ash stream events for this session — see [Sessions And Streaming](../advanced/runs-and-streaming.md). |
+| `session`     | Serializable session cursor (`sessionId`, `continuationToken`, `streamIndex`).                            |
+| `sendMessage` | Send plain text.                                                                                          |
+| `send`        | Send the full turn payload (multi-part messages, HITL responses).                                         |
+| `stop`        | Abort the active request.                                                                                 |
+| `reset`       | Clear local events, data, errors, and the local session cursor.                                           |
 
 Most chat UIs only need `data.messages` and `status`. Reach for `events` when
 you want to render lower-level activity (tool calls, reasoning deltas) the
@@ -286,7 +286,7 @@ const agent = useAshAgent({
 ```
 
 `agent.data.tools` now drives the UI. The reducer sees the full Ash event
-stream — see [Sessions And Streaming](../runs-and-streaming.md) — plus
+stream — see [Sessions And Streaming](../advanced/runs-and-streaming.md) — plus
 client-side projection events (`client.message.submitted`,
 `client.message.failed`, `client.input.responded`) for optimistic updates.
 
@@ -323,6 +323,6 @@ To change credentials without remounting, pass a function to `auth` or
 ## What To Read Next
 
 - [Next.js](./nextjs.md)
-- [Sessions And Streaming](../runs-and-streaming.md)
+- [Sessions And Streaming](../advanced/runs-and-streaming.md)
 - [Human In The Loop](../human-in-the-loop.md)
-- [Hooks](../hooks.md)
+- [Hooks](../advanced/hooks.mdx)

package/dist/docs/public/getting-started.mdx

@@ -174,3 +174,5 @@ curl -X POST http://127.0.0.1:3000/ash/v1/session/<sessionId> \
 - [Skills](./skills.md) for on-demand procedures
 - [Tools](./tools.mdx) for typed integrations
 - [Sessions And Streaming](./runs-and-streaming.md) for the durable session model
+- [Nuxt Integration](./frontend/nuxt.md) for Nuxt apps
+- [`useAshAgent` (Vue)](./frontend/use-ash-agent-vue.md) for Vue composable usage

package/dist/src/channel/websocket-upgrade-server.d.ts

@@ -0,0 +1,26 @@
+import { type Server } from "node:http";
+import type { WebSocketRouteHandler } from "#channel/routes.js";
+/**
+ * Escape hatch for SDKs and frameworks that need a Node HTTP server-shaped
+ * upgrade target inside an Ash `WS()` route.
+ *
+ * Prefer normal `WS()` lifecycle hooks for Ash-owned websocket behavior. Use
+ * this bridge only when an integration expects to register
+ * `httpServer.on("upgrade", ...)` handlers itself. The server is intentionally
+ * not listening on a port; Ash forwards only the matched route's raw Node
+ * upgrade into it.
+ */
+export interface WebSocketUpgradeServerBridge {
+    readonly route: WebSocketRouteHandler;
+    readonly server: Server;
+}
+/**
+ * Creates an escape-hatch Node HTTP server facade plus a `WS()` route handler
+ * that forwards matched raw upgrade events into that server.
+ *
+ * Prefer authoring websocket behavior directly with `WS()` hooks. Reach for
+ * this only when an SDK or framework binds to `http.Server` upgrade events,
+ * such as `engine.attach(server, path, ...)`. It works only on hosts where
+ * Nitro exposes a Node upgrade tuple for the matched WebSocket route.
+ */
+export declare function createWebSocketUpgradeServer(): WebSocketUpgradeServerBridge;

package/dist/src/channel/websocket-upgrade-server.js

@@ -0,0 +1 @@
+import{createServer}from"node:http";function createWebSocketUpgradeServer(){let t=createServer();return{route:createWebSocketUpgradeRoute(t),server:t}}function createWebSocketUpgradeRoute(e){return()=>({upgrade(t){return dispatchNodeUpgrade(e,t)}})}async function dispatchNodeUpgrade(e,t){let n=resolveNodeUpgrade(t);if(n===null)return Response.json({error:`This WebSocket route cannot expose a Node upgrade event on the current host.`,ok:!1},{status:501});let r=e.listeners(`upgrade`);if(r.length===0)return Response.json({error:`No upgrade listeners are registered on this WebSocket server bridge.`,ok:!1},{status:500});for(let t of r)await Promise.resolve(t.call(e,n.request,n.socket,n.head));return{handled:!0}}function resolveNodeUpgrade(e){let t=e.runtime?.node,n=t?.req,r=t?.upgrade?.socket,i=t?.upgrade?.head;if(n===void 0||r===void 0||i===void 0)return null;if(typeof n.url!=`string`||n.url.length===0){let t=new URL(e.url);n.url=`${t.pathname}${t.search}`}return{head:i,request:n,socket:r}}export{createWebSocketUpgradeServer};