experimental-ash 0.61.0 → 0.63.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/skills/ash-add-agent/SKILL.md

@@ -20,7 +20,6 @@ app/
 next.config.ts
 package.json
 tsconfig.json
-vercel.json      # generated/updated by withAsh()
 ```
 
 ## Steps
@@ -52,28 +51,43 @@ Use the model requested by the user or the project standard.
 
 3. Add the Ash HTTP channel:
 
+First inspect the existing Next.js app for authentication. Reuse its current provider and session
+model instead of introducing a second auth system. Look for Auth.js, Clerk, application session
+cookies, bearer-token middleware, or another established request-auth helper.
+
 ```ts
 // agent/channels/ash.ts
 import { ashChannel } from "experimental-ash/channels/ash";
 import { type AuthFn, localDev, vercelOidc } from "experimental-ash/channels/auth";
 
-function exampleProductionAuth(): AuthFn<Request> {
-  return () => {
-    if (process.env.VERCEL_ENV === "production") {
-      throw new Error(
-        "Configure production auth in agent/channels/ash.ts (e.g. Auth.js or Clerk).",
-      );
-    }
-    return null;
+const authenticateUser: AuthFn = async (request) => {
+  // Replace this call with the app's existing Auth.js, Clerk, or session helper.
+  const user = await authenticate(request);
+  if (!user) return null;
+
+  return {
+    attributes: {},
+    authenticator: "app",
+    issuer: "nextjs",
+    principalId: user.id,
+    principalType: "user",
   };
-}
+};
 
 export default ashChannel({
-  auth: [localDev(), vercelOidc(), exampleProductionAuth()],
+  auth: [localDev(), vercelOidc(), authenticateUser],
 });
 ```
 
-An authored `agent/channels/ash.ts` replaces Ash's framework default `ash` channel. Keep `localDev()` for localhost and the REPL, keep `vercelOidc()` so Vercel services can reach the deployed agent, and replace `exampleProductionAuth()` with the app's real user auth before production. If the app already uses Auth.js, Clerk, or another session provider, wire it here instead of leaving the placeholder.
+An authored `agent/channels/ash.ts` replaces Ash's framework default `ash` channel. Keep
+`localDev()` for localhost and the REPL, keep `vercelOidc()` so Vercel services can reach the
+deployed agent, and implement `authenticateUser` with the app's real user auth. If the app already
+uses Auth.js, Clerk, or another session provider, wire that existing provider here.
+
+For same-origin cookie auth, the browser already sends the session cookie and the channel should
+validate it from `request`. For bearer or custom-header auth, also configure the frontend's
+`useAshAgent({ auth })` or `useAshAgent({ headers })` call. Do not report the frontend as
+production-ready until unauthenticated requests are rejected.
 
 4. Merge package imports only when agent files use `#...` aliases:
 
@@ -149,10 +163,6 @@ Keep an existing `typecheck` unless it excludes `agent/**/*.ts`.
 
 Add `paths` only if the project uses those aliases.
 
-8. Let `withAsh()` generate or update `vercel.json`.
-
-After adding `withAsh()`, run `pnpm dev` or the relevant build command. Do not hand-author the Vercel services config unless generation fails or the user explicitly wants manual control. If `vercel.json` is created or changed, review and commit it.
-
 ## Verify
 
 ```bash
@@ -163,4 +173,6 @@ curl http://localhost:3000/ash/v1/health
 
 Use `pnpm info:ash` or `pnpm dev:ash` to inspect Ash directly.
 
-If `agent/channels/ash.ts` throws in production, that is intentional until production auth is wired.
+Verify the selected auth path as well as the health route. Local development may be accepted by
+`localDev()`, but a production-style unauthenticated request must be rejected by the end-user auth
+policy.

package/dist/skills/ash-add-next/SKILL.md

@@ -13,6 +13,8 @@ Convert an Ash-only project into a combined Next.js app plus Ash agent. Preserve
 ```txt
 agent/
   agent.ts
+  channels/
+    ash.ts
   instructions.md
 app/
   globals.css
@@ -22,7 +24,6 @@ next.config.ts
 next-env.d.ts
 package.json
 tsconfig.json
-vercel.json      # generated/updated by withAsh()
 ```
 
 ## Steps
@@ -78,7 +79,57 @@ const nextConfig: NextConfig = {};
 export default withAsh(nextConfig);
 ```
 
-4. Make Next own the main scripts:
+4. Choose how frontend users authenticate to the Ash channel.
+
+Inspect `agent/channels/ash.ts` first and preserve any existing auth policy. A channel configured
+only with `localDev()` and `vercelOidc()` does not have end-user authentication. If the project does
+not already have end-user authentication, ask the user which production access model they want
+before adding one:
+
+- **Clerk or Auth.js** for a normal signed-in web application.
+- **Existing cookie/session auth** when another application auth system is already planned.
+- **Bearer/JWT auth** when a separate client or identity provider supplies access tokens.
+- **HTTP Basic** for a small private or internal frontend where a shared credential is acceptable.
+- **Local-only for now** when they are only prototyping. Keep `localDev()` and `vercelOidc()`, clearly
+  state that browser users cannot access the deployed agent, and do not describe production setup as
+  complete.
+
+Do not choose Clerk, Auth.js, or another provider on the user's behalf when starting from an
+Ash-only project. Once the user chooses, install and configure that provider using its established
+Next.js pattern, then connect the resulting request identity to `agent/channels/ash.ts`.
+
+For cookie or session authentication, use this channel shape:
+
+```ts
+// agent/channels/ash.ts
+import { ashChannel } from "experimental-ash/channels/ash";
+import { type AuthFn, localDev, vercelOidc } from "experimental-ash/channels/auth";
+
+const authenticateUser: AuthFn = async (request) => {
+  // Implement this with the selected Clerk, Auth.js, or application session API.
+  const user = await authenticate(request);
+  if (!user) return null;
+
+  return {
+    attributes: {},
+    authenticator: "app",
+    issuer: "nextjs",
+    principalId: user.id,
+    principalType: "user",
+  };
+};
+
+export default ashChannel({
+  auth: [localDev(), vercelOidc(), authenticateUser],
+});
+```
+
+Same-origin cookie sessions need no client credential plumbing. For bearer/JWT or custom-header
+auth, also configure the generated frontend with `useAshAgent({ auth })` or
+`useAshAgent({ headers })`. For HTTP Basic, use the Ash channel auth helper and keep the credential
+outside source control.
+
+5. Make Next own the main scripts:
 
 ```json
 {
@@ -93,7 +144,7 @@ export default withAsh(nextConfig);
 }
 ```
 
-5. Use a Next-compatible `tsconfig.json`, keep `.ash/**/*.d.ts` in `include`, and preserve Ash aliases:
+6. Use a Next-compatible `tsconfig.json`, keep `.ash/**/*.d.ts` in `include`, and preserve Ash aliases:
 
 ```json
 {
@@ -122,11 +173,7 @@ export default withAsh(nextConfig);
 
 Merge matching `package.json` `imports` when Ash files use `#...`.
 
-6. Let `withAsh()` generate or update `vercel.json`.
-
-After adding `withAsh()`, run `pnpm dev` or the relevant build command. Do not hand-author the Vercel services config unless generation fails or the user explicitly wants manual control. If `vercel.json` is created or changed, review and commit it.
-
-7. Ignore generated artifacts if needed: `.next`, `.ash`, `.output`, `*.tsbuildinfo`. Do not ignore `vercel.json` when it is generated for the app.
+7. Ignore generated artifacts if needed: `.next`, `.vercel`, `.ash`, `.output`, `*.tsbuildinfo`.
 
 ## Verify
 
@@ -135,3 +182,6 @@ pnpm install
 pnpm dev
 curl http://localhost:3000/ash/v1/health
 ```
+
+Also verify the chosen authentication path. A signed-in or correctly credentialed request should
+reach the Ash session API, while an unauthenticated production-style request should return `401`.