experimental-ash 0.42.0 → 0.43.0

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

@@ -0,0 +1,332 @@
+---
+title: "useAshAgent"
+description: "React hook for building chat and agent UIs against an Ash agent."
+---
+
+`useAshAgent()` is the easiest way to put an Ash agent behind a React UI.
+
+It gives a component everything it needs to feel responsive:
+
+- **One send call** — text, attachments, and human-in-the-loop responses go through a single API
+- **Live streaming** — assistant text, reasoning, tool calls, and tool results stream as they happen
+- **Composer state** — `ready`, `submitted`, `streaming`, `error`, plus `stop()` and `reset()` built in
+- **AI SDK compatible** — `messages` are `UIMessage[]`, so they drop straight into AI SDK UI primitives
+- **Resumable sessions** — persist a single cursor and pick the conversation back up after reload
+
+## Basic Usage
+
+```tsx
+"use client";
+
+import { useAshAgent } from "experimental-ash/react";
+
+export function Chat() {
+  const agent = useAshAgent();
+  const isBusy = agent.status === "submitted" || agent.status === "streaming";
+
+  return (
+    <form
+      onSubmit={(event) => {
+        event.preventDefault();
+        const form = new FormData(event.currentTarget);
+        const message = String(form.get("message") ?? "").trim();
+        if (message.length > 0) {
+          void agent.sendMessage(message);
+        }
+      }}
+    >
+      {agent.data.messages.map((message) => (
+        <article key={message.id}>
+          <header>{message.role}</header>
+          {message.parts.map((part, index) =>
+            part.type === "text" ? <p key={index}>{part.text}</p> : null,
+          )}
+        </article>
+      ))}
+      <input name="message" disabled={isBusy} />
+      <button disabled={isBusy} type="submit">
+        Send
+      </button>
+    </form>
+  );
+}
+```
+
+By default, the hook targets same-origin Ash routes such as
+`/ash/v1/session`. In Next.js apps, pair it with [`withAsh()`](./nextjs.md) so
+your component can call the agent without configuring a separate URL.
+
+## Returned State
+
+`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.                                  |
+
+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
+default reducer doesn't surface.
+
+## Render Messages
+
+By default, `useAshAgent()` returns chat-style message data:
+
+```ts
+type AshMessageData = {
+  readonly messages: readonly AshMessage[];
+};
+```
+
+`AshMessage` follows the AI SDK `UIMessage` convention, so `messages` drops
+into any AI SDK UI primitive that accepts a `UIMessage[]`. Parts include user
+text, assistant text, reasoning, tool calls, tool results, and input requests.
+
+To project events into a different shape, pass your own
+[reducer](#custom-reducers).
+
+## Send A Message
+
+Use `sendMessage()` for plain text:
+
+```tsx
+await agent.sendMessage("Summarize this session.");
+```
+
+Use `send()` when you need the full turn payload:
+
+```tsx
+await agent.send({
+  message: [
+    { type: "text", text: "What is in this file?" },
+    {
+      type: "file",
+      // base64 data URL — e.g. "data:application/pdf;base64,JVBERi0..."
+      data: fileDataUrl,
+      mediaType: "application/pdf",
+      filename: "report.pdf",
+    },
+  ],
+});
+```
+
+## Human-In-The-Loop Responses
+
+When the stream asks for input, send responses back through the same session:
+
+```tsx
+await agent.send({
+  inputResponses: [
+    {
+      requestId,
+      optionId: "approve",
+    },
+  ],
+});
+```
+
+The default reducer marks the matching tool part as responded immediately, then
+updates it again when Ash streams the resumed result.
+
+## Stop Or Reset
+
+`stop()` aborts the active request:
+
+```tsx
+agent.stop();
+```
+
+`reset()` clears local events, data, errors, and the local session cursor:
+
+```tsx
+agent.reset();
+```
+
+Use `reset()` when you want the next `sendMessage()` call to start a fresh
+durable session.
+
+## Persist Session State
+
+Persist `session` when you want to resume a browser conversation after reload:
+
+```tsx
+const [initialSession] = useState(() => {
+  const raw = localStorage.getItem("ash-session");
+  return raw ? JSON.parse(raw) : undefined;
+});
+
+const agent = useAshAgent({
+  initialSession,
+  onSessionChange(session) {
+    localStorage.setItem("ash-session", JSON.stringify(session));
+  },
+});
+```
+
+The session snapshot contains the `sessionId`, `continuationToken`, and
+`streamIndex`. Store the full object, not just one field.
+
+## Add Per-Turn Client Context
+
+Use `prepareSend` to attach fresh browser state before each request:
+
+```tsx
+const agent = useAshAgent({
+  prepareSend(input) {
+    return {
+      ...input,
+      clientContext: {
+        pathname: window.location.pathname,
+        // any other page-scoped state you want the model to see
+        selectedRepository,
+      },
+    };
+  },
+});
+```
+
+`clientContext` is rendered as ephemeral model context for the next turn only.
+It is never persisted to durable message history.
+
+Use authored lifecycle hooks for server-side enrichment:
+
+```ts
+// agent/hooks/profile.ts
+import { defineHook } from "experimental-ash/hooks";
+
+export default defineHook({
+  lifecycle: {
+    async session(_input, ctx) {
+      return {
+        modelContext: [
+          {
+            role: "system",
+            content: `Session ${ctx.session.sessionId} has server-side profile context.`,
+          },
+        ],
+      };
+    },
+  },
+});
+```
+
+The useful split is:
+
+- React `prepareSend`: page state from the browser
+- Ash `agent/hooks/*.ts`: runtime state, durable context, policy, and dynamic
+  skills
+
+## Custom Hosts And Headers
+
+Pass `host` when the Ash server is not same-origin:
+
+```tsx
+const agent = useAshAgent({
+  host: "https://agent.example.com",
+});
+```
+
+Pass `auth` or `headers` when the Ash channel requires credentials:
+
+```tsx
+const agent = useAshAgent({
+  auth: {
+    bearer: async () => await getAccessToken(),
+  },
+});
+```
+
+Function-valued credentials are resolved before every HTTP request.
+
+## Custom Reducers
+
+Write a reducer when you want your own UI shape derived from the raw event
+stream — the default chat projection isn't the right fit. For example, an
+agent dashboard that tracks every tool call as it happens:
+
+```tsx
+type ToolActivity = {
+  readonly callId: string;
+  readonly toolName: string;
+  readonly status: "running" | "completed" | "failed";
+};
+
+const agent = useAshAgent({
+  reducer: {
+    initial() {
+      return { tools: [] as readonly ToolActivity[] };
+    },
+    reduce(data, event) {
+      if (event.type === "actions.requested") {
+        const started: ToolActivity[] = event.data.actions
+          .filter((action) => action.kind === "tool-call")
+          .map((action) => ({
+            callId: action.callId,
+            toolName: action.toolName,
+            status: "running",
+          }));
+        return { tools: [...data.tools, ...started] };
+      }
+      if (event.type === "action.result" && event.data.result.kind === "tool-result") {
+        const { callId } = event.data.result;
+        return {
+          tools: data.tools.map((tool) =>
+            tool.callId === callId ? { ...tool, status: event.data.status } : tool,
+          ),
+        };
+      }
+      return data;
+    },
+  },
+});
+```
+
+`agent.data.tools` now drives the UI. The reducer sees the full Ash event
+stream — see [Sessions And Streaming](../runs-and-streaming.md) — plus
+client-side projection events (`client.message.submitted`,
+`client.message.failed`, `client.input.responded`) for optimistic updates.
+
+## Lifecycle Callbacks
+
+Use callbacks for side effects:
+
+```tsx
+const agent = useAshAgent({
+  onEvent(event) {
+    console.debug("ash event", event.type);
+  },
+  onError(error) {
+    reportError(error);
+  },
+  onFinish(snapshot) {
+    console.debug("turn finished", snapshot.status);
+  },
+});
+```
+
+## When Options Change
+
+`host`, `auth`, `headers`, `initialSession`, `reducer`, and
+`maxReconnectAttempts` are read once when the hook creates its internal store.
+Remount the component to switch them.
+
+Callback functions (`onEvent`, `onError`, `onFinish`, `onSessionChange`,
+`prepareSend`) are refreshed on every render.
+
+To change credentials without remounting, pass a function to `auth` or
+`headers` — the underlying client invokes it before every HTTP request.
+
+## What To Read Next
+
+- [Next.js](./nextjs.md)
+- [Sessions And Streaming](../runs-and-streaming.md)
+- [Human In The Loop](../human-in-the-loop.md)
+- [Hooks](../hooks.md)

package/dist/docs/public/{getting-started.md → getting-started.mdx}

@@ -6,6 +6,15 @@ description: "Install, create your first agent, and run it locally."
 This guide gets a small Ash app running locally and shows the current request loop: build, run,
 message, stream, and follow up.
 
+<CopyPrompt text="Set up an Ash app, a filesystem-first framework for durable agents. In the user's project, scaffold a new Ash app with pnpm create experimental-ash-agent if no app exists, or add experimental-ash to an existing app. Ensure agent/instructions.md and agent/agent.ts exist, add a first typed weather tool under agent/tools/get_weather.ts, run the local dev workflow, create a session, attach to the stream, and send a follow-up. Adapt model and provider choices to the project, and do not commit unless the user asks.">
+  Set up an Ash app, a filesystem-first framework for durable agents. In the user's project,
+  scaffold a new Ash app with pnpm create experimental-ash-agent if no app exists, or add
+  experimental-ash to an existing app. Ensure agent/instructions.md and agent/agent.ts exist, add a
+  first typed weather tool under agent/tools/get_weather.ts, run the local dev workflow, create a
+  session, attach to the stream, and send a follow-up. Adapt model and provider choices to the
+  project, and do not commit unless the user asks.
+</CopyPrompt>
+
 ## Prerequisites
 
 - Node `24.x`
@@ -158,8 +167,10 @@ curl -X POST http://127.0.0.1:3000/ash/v1/session/<sessionId> \
 
 ## What To Read Next
 
+- [Next.js](./frontend/nextjs.md) for running Ash behind a Next.js app
+- [`useAshAgent`](./frontend/use-ash-agent.md) for building browser chat and agent UIs
 - [Project Layout](./project-layout.md) for every supported authored slot
 - [`agent.ts`](./agent-ts.md) for runtime config
 - [Skills](./skills.md) for on-demand procedures
-- [Tools](./tools.md) for typed integrations
+- [Tools](./tools.mdx) for typed integrations
 - [Sessions And Streaming](./runs-and-streaming.md) for the durable session model

package/dist/docs/public/{human-in-the-loop.md → human-in-the-loop.mdx}

@@ -8,6 +8,17 @@ Ash supports human-in-the-loop (HITL) in two forms:
 - tool approval requests
 - explicit user questions via the framework `ask_question` tool
 
+<CopyPrompt text="Add human-in-the-loop behavior to the user's Ash project. Ash supports tool approval requests and explicit user questions through a unified InputRequest/InputResponse flow: the model requests input, Ash emits input.requested, the session parks at session.waiting, and the client or channel resumes with inputResponses or a matching follow-up message. Inspect agent/tools, agent/connections, and client or channel code, add needsApproval or connection approval with always, once, or never for sensitive actions, rely on ask_question for model-requested clarification, surface pending requests in the UI or channel, verify the parked-session resume flow, and do not commit unless the user asks.">
+  Add human-in-the-loop behavior to the user's Ash project. Ash supports tool approval requests and
+  explicit user questions through a unified InputRequest/InputResponse flow: the model requests
+  input, Ash emits input.requested, the session parks at session.waiting, and the client or channel
+  resumes with inputResponses or a matching follow-up message. Inspect agent/tools,
+  agent/connections, and client or channel code, add needsApproval or connection approval with
+  always, once, or never for sensitive actions, rely on ask_question for model-requested
+  clarification, surface pending requests in the UI or channel, verify the parked-session resume
+  flow, and do not commit unless the user asks.
+</CopyPrompt>
+
 Both use the same unified `InputRequest` / `InputResponse` protocol:
 
 1. the model requests input
@@ -250,5 +261,5 @@ If you press `Escape` and then send a normal message, the pending requests are i
 ## What To Read Next
 
 - [`agent.ts`](./agent-ts.md)
-- [Tools](./tools.md)
+- [Tools](./tools.mdx)
 - [Sessions And Streaming](./runs-and-streaming.md)

package/dist/docs/public/meta.json

@@ -8,6 +8,7 @@
     "human-in-the-loop",
     "sandbox",
     "channels",
+    "frontend",
     "subagents",
     "schedules",
     "connections",

package/dist/docs/public/sandbox.md

@@ -441,7 +441,7 @@ Important behavior:
 
 ## What To Read Next
 
-- [Tools](./tools.md)
+- [Tools](./tools.mdx)
 - [Workspace](./workspace.md)
 - [Session Context](./session-context.md)
 - [Vercel Sandbox](https://vercel.com/docs/sandbox) — platform documentation for Vercel Sandbox

package/dist/docs/public/{schedules.md → schedules.mdx}

@@ -7,6 +7,15 @@ Schedules let an agent initiate recurring work — digests, syncs, maintenance,
 
 Schedules live under `schedules/` at the root agent package.
 
+<CopyPrompt text="Add a recurring schedule to the user's Ash project. Ash schedules are root-only files under agent/schedules and provide exactly one of markdown or run. Inspect existing schedules and channel files, choose a .md fire-and-forget prompt or a TypeScript defineSchedule handler with cron and run, use receive with message, args, and appAuth plus waitUntil for channel handoff when needed, keep the schedule name path-derived, verify discovery and hosted Vercel Cron output when relevant, and do not commit unless the user asks.">
+  Add a recurring schedule to the user's Ash project. Ash schedules are root-only files under
+  agent/schedules and provide exactly one of markdown or run. Inspect existing schedules and channel
+  files, choose a .md fire-and-forget prompt or a TypeScript defineSchedule handler with cron and
+  run, use receive with message, args, and appAuth plus waitUntil for channel handoff when needed,
+  keep the schedule name path-derived, verify discovery and hosted Vercel Cron output when relevant,
+  and do not commit unless the user asks.
+</CopyPrompt>
+
 ## Boundaries
 
 - schedules are root-only — local subagents cannot declare `schedules/`

package/dist/docs/public/skills.md

@@ -205,5 +205,5 @@ For most apps:
 ## What To Read Next
 
 - [Context Control](./context-control.md)
-- [Tools](./tools.md)
-- [Subagents](./subagents.md)
+- [Tools](./tools.mdx)
+- [Subagents](./subagents.mdx)

package/dist/docs/public/{subagents.md → subagents.mdx}

@@ -11,6 +11,16 @@ A subagent is just an agent that lives under `agent/subagents/<id>/`. It is auth
 `defineAgent` helper as the root agent — the location under `subagents/` is what makes it a
 subagent.
 
+<CopyPrompt text="Add a specialist subagent to the user's Ash project. Local subagents live under agent/subagents/id, require agent.ts plus instructions.md or instructions.ts, and need a description so the parent agent knows when to delegate. Inspect the existing subagent tree, choose a local subagent or defineRemoteAgent as appropriate, add focused instructions and any scoped tools, skills, sandbox files, or nested subagents, remember that skills and sandboxes do not cross the parent-child boundary, verify the parent sees the lowered subagent tool and child session stream, and do not commit unless the user asks.">
+  Add a specialist subagent to the user's Ash project. Local subagents live under
+  agent/subagents/id, require agent.ts plus instructions.md or instructions.ts, and need a
+  description so the parent agent knows when to delegate. Inspect the existing subagent tree, choose
+  a local subagent or defineRemoteAgent as appropriate, add focused instructions and any scoped
+  tools, skills, sandbox files, or nested subagents, remember that skills and sandboxes do not cross
+  the parent-child boundary, verify the parent sees the lowered subagent tool and child session
+  stream, and do not commit unless the user asks.
+</CopyPrompt>
+
 ## What A Local Subagent Looks Like
 
 ```text

package/dist/docs/public/{tools.md → tools.mdx}

@@ -8,6 +8,17 @@ Tools are Ash's typed executable integrations.
 Use a tool when the model should call real code with structured input and get structured output
 back.
 
+<CopyPrompt text="Add a typed Ash tool to the user's project. Ash tools live under agent/tools, and the model-facing tool name comes from the filename. Inspect existing agent/tools and agent/lib, then create or update the smallest agent/tools/snake_case_name.ts file using defineTool from experimental-ash/tools with a Zod or Standard Schema inputSchema and an inline execute(input, ctx). Use ctx.session, ctx.getSandbox(), or ctx.getSkill only inside runtime execution when needed, keep secrets in environment variables, bound large outputs or use toModelOutput and retentionPolicy, verify with the project's typecheck and tests, and do not commit unless the user asks.">
+  Add a typed Ash tool to the user's project. Ash tools live under agent/tools, and the model-facing
+  tool name comes from the filename. Inspect existing agent/tools and agent/lib, then create or
+  update the smallest agent/tools/snake_case_name.ts file using defineTool from
+  experimental-ash/tools with a Zod or Standard Schema inputSchema and an inline execute(input,
+  ctx). Use ctx.session, ctx.getSandbox(), or ctx.getSkill only inside runtime execution when
+  needed, keep secrets in environment variables, bound large outputs or use toModelOutput and
+  retentionPolicy, verify with the project's typecheck and tests, and do not commit unless the user
+  asks.
+</CopyPrompt>
+
 ## The Main API
 
 `agent/tools/get_weather.ts`
@@ -362,7 +373,7 @@ platform-specific output (e.g. Slack Block Kit) from structured tool data that t
 needs to see.
 
 Use `toolResultFrom(result, toolDefinition)` to narrow an `action.result` to a specific tool and
-get typed output. See [Hooks — Narrowing tool results](./hooks.md#narrowing-tool-results) for the
+get typed output. See [Hooks — Narrowing tool results](./hooks.mdx#narrowing-tool-results) for the
 full API.
 
 Note: `retentionPolicy` and `onCompact` operate on the projected output (what the model sees),
@@ -370,23 +381,23 @@ not the full `execute` return.
 
 ## Dynamic Tools
 
-Dynamic tools resolve at runtime based on session context — tenant configuration, feature flags, user roles, or external data. Use `defineTools` with an `events` object to produce tools dynamically.
+Dynamic tools resolve at runtime based on session context — tenant configuration, feature flags, user roles, or external data. Use `defineDynamic` with an `events` object to produce tools dynamically.
 
 ### Single Dynamic Tool
 
 `agent/tools/analytics.ts`
 
 ```ts
-import { defineTool, tool } from "experimental-ash/tools";
+import { defineDynamic, defineTool } from "experimental-ash/tools";
 import { z } from "zod";
 
-export default defineTool({
+export default defineDynamic({
   events: {
     "session.started": async (event, ctx) => {
       const flags = await fetchFeatureFlags(ctx.session.id);
       if (!flags.advancedAnalytics) return null;
 
-      return tool({
+      return defineTool({
         description: "Run an advanced analytics query.",
         inputSchema: z.object({ query: z.string() }),
         async execute(input) {
@@ -398,24 +409,24 @@ export default defineTool({
 });
 ```
 
-Return `null` to produce no tool. The tool name is the file slug (`analytics`), identical to a static `defineTool`. Entries must be wrapped with `tool()` — this stamps the entry for the bundler transform so `execute` functions survive workflow step boundaries.
+Return `null` to produce no tool. The tool name is the file slug (`analytics`), identical to a static `defineTool`. Entries must be wrapped with `defineTool()` — this stamps the entry for the bundler transform so `execute` functions survive workflow step boundaries.
 
 ### Multiple Dynamic Tools
 
 `agent/tools/tenant.ts`
 
 ```ts
-import { defineTools, tool } from "experimental-ash/tools";
+import { defineDynamic, defineTool } from "experimental-ash/tools";
 import { z } from "zod";
 
-export default defineTools({
+export default defineDynamic({
   events: {
     "session.started": async (event, ctx) => {
       const tenant = await fetchTenant(ctx.session.id);
       if (!tenant) return null;
 
       return {
-        export: tool({
+        export: defineTool({
           description: `Export ${tenant.name} data`,
           inputSchema: z.object({ format: z.enum(["csv", "json"]) }),
           async execute(input) {
@@ -423,7 +434,7 @@ export default defineTools({
             return callTenantApi(tenant.apiUrl, "export", input.format);
           },
         }),
-        query: tool({
+        query: defineTool({
           description: `Query ${tenant.name} data`,
           inputSchema: z.object({ sql: z.string() }),
           async execute(input) {
@@ -437,19 +448,19 @@ export default defineTools({
 });
 ```
 
-Each entry must be wrapped with `tool()` — it captures the schema type so `execute(input)` is inferred from `inputSchema`, matching the AI SDK's `tool()` pattern.
+Each entry must be wrapped with `defineTool()` — it captures the schema type so `execute(input)` is inferred from `inputSchema`, matching the AI SDK's `tool()` pattern.
 
 ### Tool Naming
 
 Dynamic tool names are derived from the file path and the definition function:
 
-| Definition    | File                       | Entry keys        | Tool name(s)                      |
-| ------------- | -------------------------- | ----------------- | --------------------------------- |
-| `defineTool`  | `agent/tools/analytics.ts` | _(single entry)_  | `analytics`                       |
-| `defineTools` | `agent/tools/tenant.ts`    | `export`, `query` | `tenant__export`, `tenant__query` |
-| `defineTools` | `agent/tools/search.ts`    | `run`             | `search__run`                     |
+| Definition                      | File                       | Entry keys        | Tool name(s)                      |
+| ------------------------------- | -------------------------- | ----------------- | --------------------------------- |
+| `defineDynamic` (single return) | `agent/tools/analytics.ts` | _(single entry)_  | `analytics`                       |
+| `defineDynamic` (map return)    | `agent/tools/tenant.ts`    | `export`, `query` | `tenant__export`, `tenant__query` |
+| `defineDynamic` (map return)    | `agent/tools/search.ts`    | `run`             | `search__run`                     |
 
-`defineTool` always produces one tool named after the file slug — identical to static tools. `defineTools` always uses `slug__key`, even when the resolver returns a single entry. This keeps names stable: adding a second entry to a `defineTools` file does not rename the first.
+`defineDynamic` with a single return always produces one tool named after the file slug — identical to static tools. `defineDynamic` with a map return always uses `slug__key`, even when the resolver returns a single entry. This keeps names stable: adding a second entry to a `defineDynamic` file does not rename the first.
 
 ### Events
 
@@ -478,17 +489,21 @@ The tool-loop reads the current tool set right before each model call. If an eve
 A single file can declare handlers for multiple events. The result of the most recently fired handler owns the tool set for that file:
 
 ```ts
-import { defineTools, tool } from "experimental-ash/tools";
+import { defineDynamic, defineTool } from "experimental-ash/tools";
 
-export default defineTools({
+export default defineDynamic({
   events: {
     "session.started": async (event, ctx) => {
-      return { query: tool({ description: "Query", inputSchema: {}, execute: async () => {} }) };
+      return {
+        query: defineTool({ description: "Query", inputSchema: {}, execute: async () => {} }),
+      };
     },
     "turn.started": async (event, ctx) => {
       // On each turn, re-resolve tools. Replaces this file's
       // session.started tools for subsequent calls.
-      return { search: tool({ description: "Search", inputSchema: {}, execute: async () => {} }) };
+      return {
+        search: defineTool({ description: "Search", inputSchema: {}, execute: async () => {} }),
+      };
     },
   },
 });
@@ -496,11 +511,11 @@ export default defineTools({
 
 ### Type Inference
 
-`inputSchema` accepts Zod, Standard Schema, or plain JSON Schema — same as static `defineTool`. When using Zod, the `tool()` wrapper infers the `execute` input type automatically:
+`inputSchema` accepts Zod, Standard Schema, or plain JSON Schema — same as static `defineTool`. When using Zod, the `defineTool()` wrapper infers the `execute` input type automatically:
 
 ```ts
 return {
-  query: tool({
+  query: defineTool({
     inputSchema: z.object({ city: z.string() }),
     async execute(input) {
       // input.city is typed as string
@@ -517,17 +532,17 @@ The `execute` signature matches static tools: `execute(input: TInput, ctx: ToolC
 `execute` can live inside helper functions, `.map()` callbacks, or IIFEs — the bundler transform follows nested scopes and captures all referenced variables:
 
 ```ts
-import { defineTools, tool } from "experimental-ash/tools";
+import { defineDynamic, defineTool } from "experimental-ash/tools";
 import { z } from "zod";
 
-export default defineTools({
+export default defineDynamic({
   events: {
     "session.started": async (event, ctx) => {
       const tenant = await fetchTenant(ctx.session.id);
 
       function buildTool(action: string) {
         const endpoint = `${tenant.apiUrl}/${action}`;
-        return tool({
+        return defineTool({
           description: `${action} for ${tenant.name}`,
           inputSchema: z.object({ query: z.string() }),
           async execute(input) {

package/dist/src/channel/adapter.d.ts

@@ -75,6 +75,8 @@ export interface FetchFileResult {
     readonly mediaType?: string;
     readonly filename?: string;
 }
+export type ChannelInstrumentationMetadata = Readonly<Record<string, unknown>>;
+export type ChannelInstrumentationMetadataProjector = (state: Record<string, unknown> | undefined) => ChannelInstrumentationMetadata;
 /**
  * Plain-object channel adapter with durable state, an optional inbound
  * delivery hook, event handlers, and optional attachment resolution.
@@ -122,6 +124,17 @@ export type ChannelAdapter<TCtx extends ChannelAdapterContext<any> = ChannelAdap
      * construction time.
      */
     readonly fetchFile?: (url: string) => Promise<Buffer | FetchFileResult | null>;
+    /**
+     * Framework-owned observability projection for the active channel.
+     *
+     * Channel implementations decide which state fields are safe and
+     * meaningful to expose to instrumentation callbacks. The harness reads
+     * the resulting projection through a seed context key rather than
+     * inspecting adapter state directly.
+     */
+    readonly instrumentation?: {
+        readonly metadata?: ChannelInstrumentationMetadataProjector;
+    };
 } & ChannelEventHandlers<TCtx>;
 /**
  * Produces the default {@link StepInput} when no custom adapter `deliver`

package/dist/src/channel/instrumentation.d.ts

@@ -0,0 +1,10 @@
+import type { ChannelAdapter, ChannelInstrumentationMetadata } from "#channel/adapter.js";
+export interface ChannelInstrumentationProjection {
+    readonly kind: string;
+    readonly metadata: ChannelInstrumentationMetadata;
+}
+export declare function buildChannelInstrumentationProjection(input: {
+    readonly adapter: ChannelAdapter;
+    readonly channelName?: string;
+    readonly existingKind?: string;
+}): ChannelInstrumentationProjection;

package/dist/src/channel/instrumentation.js

@@ -0,0 +1 @@
+import{createLogger}from"#internal/logging.js";import{getAdapterKind}from"#channel/adapter.js";import{isInstrumentationChannelKind,resolveInstrumentationProjection}from"#internal/instrumentation.js";const log=createLogger(`channel.instrumentation`);function buildChannelInstrumentationProjection(e){let{adapter:t,channelName:n,existingKind:r}=e;return{kind:resolveKind({adapter:t,channelName:n,existingKind:r}),metadata:resolveMetadata(t)}}function resolveKind(e){let{adapter:r,channelName:i,existingKind:a}=e;if(a!==void 0)return a;if(i!==void 0&&i.length>0)return`channel:${i}`;let o=getAdapterKind(r);return isInstrumentationChannelKind(o)?o:`channel:${o}`}function resolveMetadata(e){let n=e.instrumentation?.metadata;return n===void 0?{}:resolveInstrumentationProjection({invoke:()=>n(e.state),log,source:getAdapterKind(e)})??{}}export{buildChannelInstrumentationProjection};