experimental-ash 0.55.3 → 0.57.0

package/dist/docs/public/tools.mdx

@@ -64,7 +64,11 @@ The AI SDK uses `inputSchema` to validate and transform model input (including Z
 Ash accepts Zod, any Standard Schema, or a plain JSON Schema object. Zod and Standard Schema
 definitions infer the `execute(input, ctx)` input type. Plain JSON Schema is accepted at runtime, but
 TypeScript treats `input` as `Record<string, unknown>` because the schema does not carry a static
-output type.
+input type.
+
+Add `outputSchema` when the tool returns structured data. It is optional, but code mode uses it to
+type host-tool return values inside generated code. Zod and Standard Schema output schemas also type
+the value returned from `execute`.
 
 `agent/tools/lookup_customer.ts`
 
@@ -77,8 +81,12 @@ export default defineTool({
   inputSchema: z.object({
     customerId: z.string(),
   }),
+  outputSchema: z.object({
+    customerId: z.string(),
+    status: z.enum(["active", "inactive"]),
+  }),
   async execute(input) {
-    return { customerId: input.customerId };
+    return { customerId: input.customerId, status: "active" };
   },
 });
 ```

package/dist/skills/agent/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: ash-agent
+description: Public Ash guide for app authors. Use when building Ash apps, writing user-facing docs/examples, explaining project layout, or helping someone deploy and operate an Ash project. Prefer authored-file guidance, minimal examples, and end-user implementation details.
+metadata:
+  author: Ash repo
+  version: "0.0.1"
+---
+
+Use this skill for end-user Ash work.
+
+## When to use this skill
+
+Use this skill when the task is about how an app author uses Ash, including:
+
+- building an Ash app
+- writing or updating public docs and examples
+- explaining agent layout and authoring slots
+- teaching how skills, tools, the sandbox, channels, or subagents fit together
+- showing how to install Ash from npm and get started locally
+- helping someone deploy or operate an Ash app
+
+If the task is mainly about Ash internals, compiler behavior, runtime plumbing, or implementation
+constraints, load the `ash-framework` skill instead.
+
+## How to use this skill
+
+1. Start from the app author's point of view.
+2. Read the bundled references before relying on memory.
+3. Use the scripts in `scripts/` when they match the user's goal.
+4. Keep guidance task-oriented, concrete, and minimal.
+
+## Writing or updating public docs
+
+The docs website at `apps/docs` renders two directories directly:
+
+- `/docs/public` — polished public docs, manually ordered via
+  `/docs/public/meta.json`.
+- `/research/active` — active design notes, mounted under `/docs/research`
+  and listed alphabetically with no meta.json.
+
+Every markdown file in either directory that should render on the site
+**must** have this shape:
+
+```md
+---
+title: "Short page title"
+description: "One-sentence summary of the page."
+url: /custom/site/path # optional, /docs/public only; only if filename ≠ site URL
+---
+
+Body starts here. Do NOT repeat the title as an `# H1` in the body — the
+site renders the frontmatter `title` as the page heading.
+```
+
+After creating a new `/docs/public` page:
+
+- Add its slug to `/docs/public/meta.json#pages` in the section that matches
+  its topic. The slug is the filename without the `.md` extension for root
+  files, or the folder name for subfolder groups. The trailing `"..."` token
+  auto-includes anything missing but gets placed at the bottom — put new
+  pages in the intended position explicitly.
+
+New `/research/active` files need no meta.json work — the Research section
+sorts alphabetically.
+
+Files intentionally excluded from the site (the top-level `README.md` in
+each directory, etc.) should have no frontmatter and be listed in the
+EXCLUDES set of `scripts/check-docs.mjs`. `pnpm docs:check` validates every
+other file in both directories.
+
+## What Ash is
+
+Ash is a filesystem-first framework for durable backend agents.
+Authors define agents on disk with files like `instructions.md`, `skills/`, `tools/`, `sandbox/`,
+`channels/`, `subagents/`, `schedules/`, and `agent.ts`.
+
+## Core behavior to reinforce
+
+- `instructions.md` is the always-on instructions prompt.
+- `skills/` are on-demand procedures loaded only when relevant.
+- `tools/` are typed executable integrations.
+- each agent has exactly one sandbox; the workspace is the filesystem inside it.
+- `sandbox/sandbox.ts` overrides the sandbox definition and `sandbox/workspace/` seeds files; both
+  are optional and the framework supplies a default.
+- `channels/` are authored messaging-platform entrypoints and can seed durable context in
+  `onDeliver()`.
+- `getSession()`, `getSandbox()`, and `getSkill()` are public authored runtime helpers.
+- `getContext()`, `requireContext()`, `hasContext()`, `setContext()`, and `ensureContext()` are the
+  public unified context helpers.
+- channel classes can declare `static readonly contextProviders = [...]` to derive live step-local
+  values from durable context.
+- `SlackChannel` subclasses can override `handleInteraction(ctx, interaction)` for no-wake Slack UI
+  actions, use `getSlackThread()` for thread reads/posts, and call `editMessage(messageTs, renderable)`
+  to update Slack messages inline.
+- `subagents/` are specialist child agents with separate runs.
+- `schedules/` are recurring triggers.
+- `agent.ts` is where model, name, metadata, build, compaction, and workspace preferences live.
+- route auth and IP policy live on the HTTP channel layer, not in `agent.ts`.
+
+## Preferred workflow
+
+Read these bundled references in roughly this order:
+
+1. `references/getting-started.md`
+2. `references/project-layout.md`
+3. `references/skills.md`
+4. `references/runtime-model.md`
+5. `references/deployment.md`
+
+## How to explain Ash well
+
+- lead with how to use Ash, not how Ash is implemented
+- start with the authored filesystem shape and the smallest working path
+- explain when to use each authored slot and show the file path where it lives
+- use one minimal example before edge cases
+- explain that skills are discovered first and loaded through the framework-owned `load_skill` tool
+- explain current boundaries such as root-only `schedules/` when relevant
+- mention the package name is `experimental-ash` while the framework and CLI are called Ash and `ash`
+- note that route auth lives on channels and that `agent.ts` no longer owns it
+- for Slack or custom channel examples, explain the two-step context pattern: `onDeliver()` writes
+  durable keys, then `static readonly contextProviders = [...]` rebuilds live per-step values
+- for Slack UI interactions, explain that `handleInteraction(ctx, interaction)` is the subclass hook
+  for no-wake `block_actions`, `editMessage(messageTs, renderable)` edits messages inline,
+  `getSlackThread()` exposes thread reads/posts, and `SlackRenderable` is the authored output format
+- point people to packaged references instead of assuming repo docs are available
+
+Prefer feature-first framing like:
+
+- "Use a tool when you need typed executable logic."
+- "Use a sandbox when the model needs an isolated shell environment."
+- "Use a skill when you want optional procedure guidance without bloating every turn."
+
+Avoid starting with compiler, discovery, runtime, or harness internals unless the task truly requires them.
+
+## Bundled scripts
+
+Use these packaged scripts when helpful:
+
+- `scripts/bootstrap-from-npm.sh` - scaffold a new Ash app from npm
+- `scripts/add-to-existing-project.sh` - add Ash to an existing app
+- `scripts/verify-local-agent.sh` - reminder of the common local verification commands
+
+## Build, dev, and deployment expectations
+
+- `ash info` validates the authored surface and inspects the resolved app contract.
+- `ash build` compiles artifacts and builds the runtime host output.
+- `ash dev` runs the local host and interactive REPL.
+- stable runtime routes include `GET /.well-known/ash/v1/health`, `POST /.well-known/ash/v1/message`, and `GET /.well-known/ash/v1/runs/:runId/stream`
+- channel webhooks follow `POST /.well-known/ash/v1/channels/<channelId>/webhook` when channels are configured
+- recommend local development first, then Vercel deployment when shared durable hosting matters
+
+## Supporting skills
+
+When public Ash work touches adjacent systems, also load the relevant specialist skills:
+
+- `ash-framework` for compiler, runtime, discovery, or artifact internals
+- `ai-sdk` for AI SDK APIs, tool calling, and provider integration details
+- `workflow` for durable orchestration behavior and step-boundary decisions
+
+For deployment-heavy tasks, it can also help to install Vercel-maintained skills with `npx skills`
+so the agent can pull in current deployment guidance.
+
+## Completion checklist
+
+- keep the answer user-facing and task-oriented
+- if public behavior changes, update public docs too
+- prefer packaged references and scripts over repo-only links
+- run the expected quality gates before considering the work done
+- ensure public API changes are documented and covered by tests

package/dist/skills/agent/references/deployment.md

@@ -0,0 +1,35 @@
+# Deployment Reference
+
+Recommended posture:
+
+1. develop locally
+2. validate with build and checks
+3. deploy to Vercel when you need shared durable hosting
+
+## Common deployment flow
+
+```bash
+vercel login
+vercel link
+pnpm build
+vercel
+```
+
+Production deploy:
+
+```bash
+vercel --prod
+```
+
+## Verify a deployment
+
+- health route responds
+- message route returns a `runId`
+- run stream returns NDJSON lifecycle events
+- any configured channel auth still succeeds in production
+
+## Optional remote REPL
+
+```bash
+ash dev https://<deployment-url>
+```

package/dist/skills/agent/references/getting-started.md

@@ -0,0 +1,58 @@
+# Getting Started Reference
+
+Ash is a filesystem-first framework for durable backend agents.
+
+## Install from npm
+
+The framework is called Ash, the published npm package is `experimental-ash`,
+and the scaffolder package is `create-experimental-ash-agent`.
+
+Guided setup for a human (the wizard asks for each decision):
+
+```bash
+pnpm create experimental-ash-agent -i
+```
+
+When an AI agent sets Ash up on the user's behalf, the create flow is **headless
+by default** — it takes flags (at minimum `<name>` and `--model`) and bails with
+`--help` rather than prompting. Don't improvise it: follow the executable
+**Onboarding** skill, which encodes model, channels (web/Slack), provisioning,
+deploy, and the browser/OAuth handoffs:
+
+- repo: `docs/public/onboarding.md`
+- Markdown: https://ash.labs.vercel.dev/llms.mdx/onboarding
+
+Slack is not a headless create channel. Scaffold/provision headlessly with
+`--channels web`, then add Slack from the project directory with the interactive
+channel setup:
+
+```bash
+ash channels add slack
+```
+
+That setup uses Vercel Connect under the hood:
+
+```bash
+vercel connect create slack --triggers --name <name>
+```
+
+Add Ash to an existing app instead:
+
+```bash
+pnpm add -D experimental-ash
+```
+
+## Smallest working path
+
+1. scaffold or create a project
+2. add `agent/instructions.md`
+3. add `agent/agent.ts`
+4. add one tool if runtime behavior is needed
+5. run `pnpm dev`
+
+## Important naming note
+
+- framework name: Ash
+- npm package name: `experimental-ash`
+- scaffolder package: `create-experimental-ash-agent`
+- CLI name: `ash`

package/dist/skills/agent/references/project-layout.md

@@ -0,0 +1,35 @@
+# Project Layout Reference
+
+Recommended layout:
+
+```text
+my-agent/
+├── package.json
+├── tsconfig.json
+└── agent/
+    ├── agent.ts
+    ├── instructions.md
+    ├── skills/
+    ├── lib/
+    ├── sandbox/
+    ├── tools/
+    ├── channels/
+    ├── schedules/
+    └── subagents/
+```
+
+## Slot guide
+
+- `instructions.md` - base instructions prompt (the legacy `system.md` slot still works with a deprecation warning)
+- `skills/` - on-demand procedures
+- `tools/` - typed executable integrations
+- `channels/` - HTTP or messaging entrypoints; `onDeliver()` writes durable context and static
+  `contextProviders` rebuild live step-local values when needed; Slack channels can override
+  `handleInteraction(...)` for no-wake UI actions
+- `sandbox/` - the agent's single sandbox; optional `sandbox.ts` override and optional
+  `workspace/` seed files
+- `subagents/` - specialist child agents (each carries its own independent `sandbox/`)
+- `schedules/` - recurring jobs
+- `agent.ts` - additive runtime config for model, name, metadata, build, compaction, and workspace
+
+Prefer the nested `agent/` layout for new apps.

package/dist/skills/agent/references/runtime-model.md

@@ -0,0 +1,24 @@
+# Runtime Model Reference
+
+Key runtime ideas for app authors:
+
+- `ash info` resolves and validates the authored surface
+- `ash build` compiles artifacts and host output
+- `ash dev` starts local development and the REPL
+- `POST /.well-known/ash/v1/message` starts or resumes a run
+- `GET /.well-known/ash/v1/runs/:runId/stream` streams lifecycle events
+
+Important mental model:
+
+- message execution is durable
+- follow-up turns can resume the same run
+- tools execute inside framework-owned runtime wrappers
+- subagents run as child runs
+- channels own auth, delivery policy, and per-turn context seeding
+- `onDeliver()` can write durable serializable context before the step runs
+- channel classes can declare `static readonly contextProviders = [...]` to rebuild live
+  non-serializable step-local values after `onDeliver()`
+- Slack channels handle custom `block_actions` inline via `handleInteraction(ctx, interaction)` and
+  use `getSlackThread()` / `editMessage(messageTs, renderable)` for Slack-native reads and updates
+- tools and other authored step code read those values through unified context helpers such as
+  `requireContext(...)`

package/dist/skills/agent/references/skills.md

@@ -0,0 +1,26 @@
+# Skills Reference
+
+Skills are Ash's on-demand procedure layer.
+
+## How skills work
+
+1. Ash discovers skills under `skills/`.
+2. The runtime advertises available skills to the model.
+3. The runtime provides a framework-owned `load_skill` tool.
+4. When the model activates a skill, that skill's instructions join the active turn context.
+
+## Rules that matter
+
+- flat skills can be simple markdown files under `skills/*.md`
+- packaged skills live under `skills/<name>/SKILL.md`
+- packaged `SKILL.md` files must include `name` and `description`
+- tools remain visible whether or not a skill is activated
+- the legacy `allowed-tools` field is not supported
+- skills are loaded through the framework-owned `load_skill` tool
+
+## When to use a skill
+
+Use a skill for optional procedures, call-routing guidance, and repeatable workflows that should not
+inflate every turn.
+
+Do not use a skill for always-on identity or typed execution.

package/dist/skills/agent/scripts/add-to-existing-project.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+pnpm add -D experimental-ash
+
+cat <<'EOF'
+Add your authored agent surface, then use:
+
+  ash info
+  ash build
+  ash dev
+EOF

package/dist/skills/agent/scripts/bootstrap-from-npm.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+APP_NAME="${1:-my-agent}"
+
+pnpm dlx experimental-ash@latest init "$APP_NAME"
+cd "$APP_NAME"
+pnpm install
+pnpm dev

package/dist/skills/agent/scripts/verify-local-agent.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cat <<'EOF'
+Common local Ash verification commands:
+
+  ash info
+  ash build
+  pnpm dev
+
+Optional durable run smoke test:
+
+  curl -X POST http://127.0.0.1:3000/.well-known/ash/v1/message \
+    -H 'content-type: application/json' \
+    -d '{"message":"Hello"}'
+EOF

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

@@ -0,0 +1,166 @@
+---
+name: ash-add-agent
+description: Add an Ash agent to an existing Next.js app. Use when turning a Next app into a combined Next.js + Ash app.
+doc:
+  title: Add Agent to Next.js
+  description: Add Ash to an existing Next.js app while keeping Next.js as the primary web app.
+---
+
+Add Ash to an existing Next.js app while keeping Next as the primary web app. Preserve existing Next config, scripts, aliases, and app files unless they conflict with Ash.
+
+## Target
+
+```txt
+agent/
+  agent.ts
+  channels/
+    ash.ts
+  instructions.md
+app/
+next.config.ts
+package.json
+tsconfig.json
+vercel.json      # generated/updated by withAsh()
+```
+
+## Steps
+
+1. Install Ash:
+
+```bash
+pnpm add experimental-ash ai zod
+```
+
+2. Add the agent root:
+
+```ts
+// agent/agent.ts
+import { defineAgent } from "experimental-ash";
+
+export default defineAgent({
+  model: "openai/gpt-5.4-mini",
+});
+```
+
+```md
+<!-- agent/instructions.md -->
+
+You are a helpful assistant running inside an Ash agent.
+```
+
+Use the model requested by the user or the project standard.
+
+3. Add the Ash HTTP channel:
+
+```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;
+  };
+}
+
+export default ashChannel({
+  auth: [localDev(), vercelOidc(), exampleProductionAuth()],
+});
+```
+
+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.
+
+4. Merge package imports only when agent files use `#...` aliases:
+
+```json
+{
+  "imports": {
+    "#*": "./agent/*",
+    "#evals/*": "./evals/*"
+  }
+}
+```
+
+5. Wrap `next.config.ts` with `withAsh()`:
+
+```ts
+import type { NextConfig } from "next";
+import { withAsh } from "experimental-ash/next";
+
+const nextConfig: NextConfig = {
+  // existing config
+};
+
+export default withAsh(nextConfig);
+```
+
+If config is already wrapped by other plugins, make `withAsh()` outermost:
+
+```ts
+export default withAsh(withSomePlugin(nextConfig));
+```
+
+If config is an async function, wrap the function export with `withAsh()` rather than rewriting its internals.
+
+6. Keep Next as the main command and add Ash-specific scripts:
+
+```json
+{
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "dev:ash": "ash dev",
+    "build:ash": "ash build",
+    "info:ash": "ash info",
+    "typecheck": "tsc --noEmit"
+  }
+}
+```
+
+Keep an existing `typecheck` unless it excludes `agent/**/*.ts`.
+
+7. Update `tsconfig.json` without clobbering existing aliases:
+
+```json
+{
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".ash/**/*.d.ts",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./*"],
+      "#*": ["./agent/*"],
+      "#evals/*": ["./evals/*"]
+    }
+  }
+}
+```
+
+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
+pnpm install
+pnpm dev
+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.