experimental-ash 0.7.2 → 0.7.4

package/CHANGELOG.md

@@ -0,0 +1,205 @@
+# experimental-ash
+
+## 0.7.4
+
+### Patch Changes
+
+- ada9d2f: chore(pkg): ship `CHANGELOG.md` in the published tarball
+
+  Adds `CHANGELOG.md` to the `files` allowlist in `packages/ash/package.json`
+  and references it from the package README. Agents installing
+  `experimental-ash` can now read `node_modules/experimental-ash/CHANGELOG.md`
+  directly to evaluate the value of upgrading without leaving the project.
+
+## 0.7.3
+
+### Patch Changes
+
+- 974071d: fix(slack,schedule): repair `ScheduleDispatcher` ↔ `slackChannel.receive` contract; honor `input.auth`
+
+  Every schedule targeting a Slack channel threw `TypeError: send is not
+a function` at cron fire. `ScheduleDispatcher.trigger` called
+  `route.receive(input, { agent, waitUntil })`, but `slackChannel.receive`
+  was designed (per #474) to receive `{ send }`. The dispatcher was the
+  broken half — it never built a `send` via `createSendFn` and never
+  honored the contract `defineChannel` documents. `slackChannel.receive`
+  also hardcoded `auth: null` and ignored `ReceiveInput.auth`, so
+  schedules could not propagate `APP_AUTH` and no cross-channel
+  programmatic initiator could thread its principal through.
+
+  The fix lands the schedule dispatcher cleanly on the `receive` / `send`
+  / `Session` vocabulary from #474: build `send` via `createSendFn`,
+  call `receive(input, { send })`, return the `Session`. Same
+  fire-and-forget discipline HTTP routes already use — the workflow
+  runtime owns terminal completion and its own failure observability,
+  so `dispatchScheduleTask` no longer awaits `handle.result` and drops
+  the logged-only `status` field from its return value.
+  `slackChannel.receive` propagates `input.auth` into `send(...)`, and
+  `ChannelConfig.receive` / `Channel.receive` / `CompiledChannel.receive`
+  gain `auth: SessionAuthContext | null` on the input shape so receive
+  implementers can read the caller's principal.
+
+  Type-system hardening so this kind of drift can't recur:
+  `ResolvedChannelDefinition.receive` was typed
+  `(...args: any[]) => Promise<any>` with an eslint-disable — the
+  escape hatch that let the dispatcher pass a wrong-shape ctx without a
+  typecheck error. Now typed precisely as `CompiledChannel["receive"]`.
+  The matching `as` casts in `resolve-channel.ts` and the `as` cast the
+  dispatcher used go away. The legacy authored `Route` shape
+  (`{ fetch, receive? }`) and every fallback that hedged between it and
+  `CompiledChannel` are deleted — dead in practice (everything authored
+  goes through `defineChannel`), and the union was the only reason the
+  `any[]` typing existed. Reintroducing the original bug shape
+  (destructuring `{ agent, waitUntil }`) now fails typecheck with
+  `Property 'agent' does not exist on type '{ send: SendFn<…> }'`
+  instead of crashing at cron fire.
+
+## 0.7.2
+
+### Patch Changes
+
+- b01d908: refactor(channels): rename the canonical session channel from `http` to `ash`
+
+  The framework's built-in session channel — the routes documented in
+  `docs/external-agent-protocol.md` (`POST /ash/v1/session`, `POST
+/ash/v1/session/:sessionId`, `GET /ash/v1/session/:sessionId/stream`) — is
+  now consistently named `"ash"` across every layer instead of being split
+  between `"http"` (in the function name) and `"default"` (in the override
+  file convention).
+
+  Breaking changes — agents that override the framework default must update:
+
+  - Import path `experimental-ash/channels/http` → `experimental-ash/channels/ash`.
+  - Function `httpChannel(...)` → `ashChannel(...)`.
+  - Type `HttpRouteInput` → `AshChannelInput`.
+  - Override file `agent/channels/default.ts` → `agent/channels/ash.ts`.
+  - Framework channel name `"default"` → `"ash"` (relevant if a project
+    uses `disableRoute()` to disable the framework default; the file must
+    now be named `ash.ts`).
+  - Auto-generated continuation tokens minted by the framework switch
+    from the `http:` prefix to `ash:`. The values stay opaque to clients;
+    the change is only visible in logs.
+
+  Why: "HTTP" said nothing useful (every channel is HTTP — Slack webhooks,
+  custom `defineChannel` routes, etc.), and "default" said nothing about
+  what the file actually was. The new name mirrors the URL prefix
+  (`/ash/v1/...`), the stream headers (`x-ash-session-id`,
+  `x-ash-stream-format`), and the package name itself, so the file convention
+  (`agent/channels/ash.ts`), the function (`ashChannel`), the import path
+  (`experimental-ash/channels/ash`), and the framework channel name (`"ash"`)
+  all say the same thing.
+
+  Migration for an existing app:
+
+  ```diff
+  - // agent/channels/default.ts
+  - import { httpChannel } from "experimental-ash/channels/http";
+  + // agent/channels/ash.ts
+  + import { ashChannel } from "experimental-ash/channels/ash";
+    import { vercelOidc } from "experimental-ash/channels/auth";
+
+  - export default httpChannel({ auth: vercelOidc() });
+  + export default ashChannel({ auth: vercelOidc() });
+  ```
+
+## 0.7.1
+
+### Patch Changes
+
+- 3e4bc51: feat(slack): restore attachment ingest + fix HITL round-trip + defineChannel `attachments` field
+
+  Two regressions introduced by the 0.6 channel redesign (#474) that
+  deleted `createSlackBaseAdapter`, plus a focused public extension
+  point on `defineChannel` for channel-owned attachment resolution.
+
+  **Attachment ingest**
+
+  `slackChannel` now folds Slack file uploads into the user turn as AI
+  SDK `FilePart`s carrying opaque `ash-attachment:` refs, and declares
+  the matching `AttachmentResolver` via the new top-level `attachments`
+  config field on `defineChannel`. The framework's existing staging
+  pipeline resolves the refs with the bot token, writes the bytes to
+  `/workspace/attachments/<sha>/<name>` in the sandbox, and hands the
+  model either inline bytes (small images and PDFs) or a sandbox path
+  the agent's filesystem tools can open. Audio and video attachments
+  are skipped; oversized or disallowed-media attachments are dropped
+  with a warning so a single bad upload never blocks the text portion
+  of a mention. The new `SlackChannelConfig.uploadPolicy` mirrors
+  `httpChannel`'s policy shape; the default cap is 25 MB.
+
+  **HITL widget round-trip**
+
+  The default `input.requested` handler used to encode `action_id` as
+  `ash_input_<requestId>_<optionId>` and decode it by splitting on `_`.
+  Since `requestId` is the AI SDK `action.callId` and always contains
+  underscores (`call_…`, `toolu_…`), the decoder silently dropped every
+  HITL click. It also only rendered buttons and only read
+  `action.value`, so radio-button and static-select widgets could
+  neither be rendered by the default handler nor parsed by the channel
+  route.
+
+  Fixed by:
+
+  - Encoding `action_id` as `ash_input:<requestId>`. The colon
+    delimiter is not valid inside an AI SDK call id, so the decode is
+    unambiguous for any `requestId` shape.
+  - Rendering radio_buttons for select-display requests with ≤6 options
+    and a static_select dropdown above that, matching pre-redesign
+    behavior.
+  - Extracting `selected_option.value` for radio / static_select clicks
+    on the route handler.
+  - Exposing the parsed selection on
+    `SlackInteractionAction.selectedOptionValue` so end-user
+    `onInteraction` handlers that render custom radio / select widgets
+    can read it too.
+
+  **`defineChannel.attachments`**
+
+  `ChannelConfig` gains an optional top-level `attachments?:
+AttachmentResolver` field, mirroring how `state`, `routes`, and
+  `events` are declared:
+
+  ```ts
+  defineChannel({
+    state: {
+      /* … */
+    },
+    routes: [
+      /* … */
+    ],
+    events: {
+      /* … */
+    },
+    attachments: myResolver,
+  });
+  ```
+
+  `AttachmentResolver` is now exported from `experimental-ash/channels`
+  so callers can type their resolver implementations cleanly. The Slack
+  channel is the first consumer; any future custom channel (Discord,
+  Teams, …) that needs an attachment resolver uses the same field.
+
+## 0.7.0
+
+### Minor Changes
+
+- 6bf383a: chore(ash): rename `system` file to `instructions` file
+
+## 0.6.2
+
+### Patch Changes
+
+- 4f875e3: Expose `messageTs` on `SlackInteractionAction` so `onInteraction` handlers can `chat.update` the clicked message in place. `ctx.slack.threadTs` resolves to the thread root when the component lives inside a thread reply, so updates targeting the clicked message previously had no way to learn its `ts`.
+- 224743e: chore: abstract sandbox types to be shared, and reuse AI SDK `Sandbox` abstraction definition where reasonable
+
+## 0.6.1
+
+### Patch Changes
+
+- ff9425d: Export `Channel` from `experimental-ash/channels` and `SlackChannelState` from `experimental-ash/channels/slack` so app authors can use `slack()` / `slackChannel()` from a `channels/slack.ts` module without the TypeScript "inferred type cannot be named" error when `declaration` is enabled. The slack helpers also stop redefining a private `SlackChannelState` and now share the canonical one from `slackChannel.ts`.
+
+## 0.6.0
+
+### Minor Changes
+
+- 90ce74f: Initial changeset release

package/dist/docs/internals/README.md

@@ -24,11 +24,11 @@ If you want the shortest path through the architecture, read these in order:
 
 ## Guides
 
-- [`../../ARCHITECTURE.md`](../../ARCHITECTURE.md) — the repo-level architecture map
-- [`core-beliefs.md`](./core-beliefs.md) — the principles behind Ash's architecture rules
-- [`mechanical-invariants.md`](./mechanical-invariants.md) — detailed constraints that should become lints or structural tests
-- [`context.md`](./context.md) — the unified context system
-- [`compiler-and-artifacts.md`](./compiler-and-artifacts.md) — how authored files become `.ash/` artifacts
-- [`discovery.md`](./discovery.md) — how the framework finds authored sources
-- [`message-runtime.md`](./message-runtime.md) — the HTTP surface and runtime execution
-- [`testing.md`](./testing.md) — test tiers and helpers
+- [Ash Architecture](../../ARCHITECTURE.md) — the repo-level architecture map
+- [Core Beliefs](./core-beliefs.md) — the principles behind Ash's architecture rules
+- [Mechanical Invariants](./mechanical-invariants.md) — detailed constraints that should become lints or structural tests
+- [Unified Context](./context.md) — the unified context system
+- [Compiler and Artifacts](./compiler-and-artifacts.md) — how authored files become `.ash/` artifacts
+- [Discovery](./discovery.md) — how the framework finds authored sources
+- [Message Runtime](./message-runtime.md) — the HTTP surface and runtime execution
+- [Testing](./testing.md) — test tiers and helpers

package/dist/docs/internals/context.md

@@ -79,7 +79,7 @@ Framework providers use a superset `FrameworkContextProvider` that also receives
 
 Authored hook lifecycle dispatch (`lifecycle.session`, `lifecycle.turn`)
 runs inside step (4)'s ALS scope, before the harness step. See
-[`./hooks.md`](./hooks.md) for the full pipeline and the
+[Hooks](./hooks.md) for the full pipeline and the
 `SessionPreparedKey` flag's failure semantics.
 
 ## Channel Context

package/dist/docs/internals/hooks.md

@@ -7,7 +7,7 @@ hooks answer the runtime.
 This page explains the discovery → compile → resolve → dispatch pipeline
 and the runtime contract every authored hook handler relies on. The
 end-user-facing reference lives at
-[`docs/public/hooks.md`](../public/hooks.md).
+[Hooks](../public/hooks.md).
 
 ## Architectural Rationale
 
@@ -196,7 +196,7 @@ documented expectations:
 
 ## Related Pages
 
-- [`docs/public/hooks.md`](../public/hooks.md) — author-facing reference
-- [`./discovery.md`](./discovery.md) — discovery layout and the unified slot walker
-- [`./context.md`](./context.md) — `AshContext` surface shared by hooks
-- [`./message-runtime.md`](./message-runtime.md) — runtime stream events
+- [Hooks](../public/hooks.md) — author-facing reference
+- [Discovery](./discovery.md) — discovery layout and the unified slot walker
+- [Unified Context](./context.md) — `AshContext` surface shared by hooks
+- [Message Runtime](./message-runtime.md) — runtime stream events

package/dist/docs/internals/message-runtime.md

@@ -48,7 +48,7 @@ step.completed → turn.completed → session.waiting / session.completed
 Failure variants: `step.failed`, `turn.failed`, `session.failed`.
 A thrown `lifecycle.session` hook produces a terminal `session.failed`;
 a thrown `lifecycle.turn` hook produces a recoverable `turn.failed`
-cascade. See [`./hooks.md`](./hooks.md).
+cascade. See [Hooks](./hooks.md).
 
 `message.appended` and `reasoning.appended` carry both delta and cumulative text. `step.completed.data.finishReason` mirrors the model-step outcome (`tool-calls` means the turn continues).
 
@@ -64,4 +64,4 @@ The runtime stores both `auth.current` and `auth.initiator`. Follow-up messages
 
 The runtime owns stream plumbing; the channel owns delivery policy. The runtime calls `channel.onEvent(event)` for each lifecycle event — the channel may transform it or perform platform side effects. The harness emits events without knowing the transport.
 
-Authored stream-event hooks fan out alongside `callAdapterEventHandler` from the same `HarnessEmitFn` composer (`workflow-steps.ts` and `continuous-runtime.ts`). Hook errors propagate through the emit composer and are caught by the existing harness error path, which emits the recoverable `turn.failed` cascade. See [`./hooks.md`](./hooks.md).
+Authored stream-event hooks fan out alongside `callAdapterEventHandler` from the same `HarnessEmitFn` composer (`workflow-steps.ts` and `continuous-runtime.ts`). Hook errors propagate through the emit composer and are caught by the existing harness error path, which emits the recoverable `turn.failed` cascade. See [Hooks](./hooks.md).

package/dist/docs/public/README.md

@@ -3,7 +3,7 @@
 This folder is for app authors using Ash as a framework.
 
 If you want to understand how to build agents with Ash, start here. If you want to understand how
-the framework is implemented internally, read [`../internals/README.md`](../internals/README.md).
+the framework is implemented internally, read [Internals](../internals/README.md).
 
 Important naming note:
 
@@ -15,26 +15,26 @@ Important naming note:
 
 Read in this order:
 
-1. [getting-started.md](./getting-started.md)
-2. [project-layout.md](./project-layout.md)
-3. [agent-ts.md](./agent-ts.md)
-4. [typescript-api.md](./typescript-api.md)
-5. [context-control.md](./context-control.md)
-6. [skills.md](./skills.md)
-7. [tools.md](./tools.md)
-8. [connections.md](./connections.md)
-9. [workspace.md](./workspace.md)
-10. [sandbox.md](./sandbox.md)
-11. [channels/README.md](./channels/README.md)
-12. [human-in-the-loop.md](./human-in-the-loop.md)
-13. [session-context.md](./session-context.md)
-14. [runs-and-streaming.md](./runs-and-streaming.md)
-15. [subagents.md](./subagents.md)
-16. [schedules.md](./schedules.md)
-17. [evals.md](./evals.md)
-18. [auth-and-route-protection.md](./auth-and-route-protection.md)
-19. [vercel-deployment.md](./vercel-deployment.md)
-20. [cli-build-and-debugging.md](./cli-build-and-debugging.md)
+1. [Getting Started](./getting-started.md)
+2. [Project Layout](./project-layout.md)
+3. [`agent.ts`](./agent-ts.md)
+4. [TypeScript API](./typescript-api.md)
+5. [Context Control](./context-control.md)
+6. [Skills](./skills.md)
+7. [Tools](./tools.md)
+8. [Connections](./connections.md)
+9. [Workspace](./workspace.md)
+10. [Sandboxes](./sandbox.md)
+11. [Channels](./channels/README.md)
+12. [Human In The Loop](./human-in-the-loop.md)
+13. [Session Context](./session-context.md)
+14. [Sessions And Streaming](./runs-and-streaming.md)
+15. [Subagents](./subagents.md)
+16. [Schedules](./schedules.md)
+17. [Evals](./evals.md)
+18. [Auth And Route Protection](./auth-and-route-protection.md)
+19. [Vercel Deployment](./vercel-deployment.md)
+20. [CLI, Build, And Debugging](./cli-build-and-debugging.md)
 
 ## The Public Mental Model
 
@@ -88,4 +88,4 @@ That is why Ash exposes two identifiers:
 
 - Minimal end-to-end example: [`../../apps/weather-agent`](../../apps/weather-agent)
 - Public API source of truth: [`../../packages/ash/src/public/index.ts`](../../packages/ash/src/public/index.ts)
-- Framework internals: [`../internals/README.md`](../internals/README.md)
+- Framework internals: [Internals](../internals/README.md)

package/dist/docs/public/agent-ts.md

@@ -1,6 +1,6 @@
 ---
 title: "agent.ts"
-description: "Configure your agent with agent.ts: model, name, metadata, and runtime options."
+description: "Configure your agent with agent.ts: model, metadata, and runtime options."
 ---
 
 `agent.ts` is the additive runtime config entrypoint for an Ash agent.
@@ -13,7 +13,6 @@ Put instructions in `instructions.md`. Put runtime settings in `agent.ts`.
 import { defineAgent } from "experimental-ash";
 
 export default defineAgent({
-  name: "support-agent",
   model: "openai/gpt-5.4-mini",
   metadata: {
     team: "support",
@@ -33,7 +32,6 @@ export default defineAgent({
 Use `agent.ts` for:
 
 - model selection
-- stable agent name
 - metadata you want preserved in runtime traces
 - human-in-the-loop policy
 - hosted-build packaging controls
@@ -41,7 +39,7 @@ Use `agent.ts` for:
 - provider-specific model options
 
 For OpenTelemetry configuration, use `instrumentation.ts` instead. See
-[`instrumentation.md`](./instrumentation.md).
+[`instrumentation.ts`](./instrumentation.md).
 
 Do not use `agent.ts` for long-form instructions. Put those in `instructions.md` (or `instructions.ts`) and
 `skills/`.
@@ -94,14 +92,21 @@ export default defineAgent({
 });
 ```
 
-## `name` And `metadata`
+## Agent Identity
 
-`name` is the public agent name you want Ash to use for this app.
+The agent's name is derived at compile time from the filesystem layout:
+
+- A root agent (its `agent.ts` sits at the app root or directly under `agent/`) takes its name
+  from the enclosing `package.json`'s `name` field.
+- A nested agent takes its name from its own directory (e.g. `subagents/researcher/agent.ts` →
+  `"researcher"`).
+
+## `metadata`
 
 `metadata` is a simple string map for app-owned labels that should travel with the resolved agent
 definition and related runtime metadata.
 
-Use them for stable identifiers, environment labels, or ownership metadata. Avoid secrets here.
+Use it for environment labels or ownership metadata. Avoid secrets here.
 
 ## `build`
 
@@ -123,7 +128,7 @@ server output instead of being bundled.
 - `model` optionally overrides the model used for compaction summaries
 
 The shared per-run workspace is configured on the sandbox, not on `agent.ts`. See
-[`workspace.md`](./workspace.md) and [`sandbox.md`](./sandbox.md).
+[Workspace](./workspace.md) and [Sandboxes](./sandbox.md).
 
 ## `humanInTheLoop`
 
@@ -147,13 +152,13 @@ Supported fields:
 Use `require-approval` when the default should be "ask first". Use `auto-allow` when the default
 should be "run immediately" and only a few named tools should still require approval.
 
-See [`human-in-the-loop.md`](./human-in-the-loop.md) for the runtime flow, `input.requested`
+See [Human In The Loop](./human-in-the-loop.md) for the runtime flow, `input.requested`
 events, and HTTP response payloads.
 
 ## Telemetry
 
 OpenTelemetry tracing is configured in `agent/instrumentation.ts`, not in `agent.ts`. See
-[`instrumentation.md`](./instrumentation.md) for setup.
+[`instrumentation.ts`](./instrumentation.md) for setup.
 
 ## Route Auth And Network Policy
 
@@ -161,8 +166,8 @@ OpenTelemetry tracing is configured in `agent/instrumentation.ts`, not in `agent
 
 Those concerns live on the HTTP channel layer instead. See:
 
-- [`auth-and-route-protection.md`](./auth-and-route-protection.md)
-- [`channels/README.md`](./channels/README.md)
+- [Auth And Route Protection](./auth-and-route-protection.md)
+- [Channels](./channels/README.md)
 
 ## A Good Default
 
@@ -172,7 +177,6 @@ For many apps, `agent.ts` stays small:
 import { defineAgent } from "experimental-ash";
 
 export default defineAgent({
-  name: "weather-agent",
   model: "openai/gpt-5.4-mini",
 });
 ```
@@ -181,7 +185,7 @@ That is enough to start. Add build and compaction settings only when you need th
 
 ## What To Read Next
 
-- [`context-control.md`](./context-control.md)
-- [`human-in-the-loop.md`](./human-in-the-loop.md)
-- [`workspace.md`](./workspace.md)
-- [`auth-and-route-protection.md`](./auth-and-route-protection.md)
+- [Context Control](./context-control.md)
+- [Human In The Loop](./human-in-the-loop.md)
+- [Workspace](./workspace.md)
+- [Auth And Route Protection](./auth-and-route-protection.md)

package/dist/docs/public/auth-and-route-protection.md

@@ -140,6 +140,6 @@ export default ashChannel({
 
 ## What To Read Next
 
-- [`agent-ts.md`](./agent-ts.md)
-- [`session-context.md`](./session-context.md)
-- [`vercel-deployment.md`](./vercel-deployment.md)
+- [`agent.ts`](./agent-ts.md)
+- [Session Context](./session-context.md)
+- [Vercel Deployment](./vercel-deployment.md)

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

@@ -93,7 +93,7 @@ The framework ships its canonical session protocol on `experimental-ash/channels
 - `ashChannel({ auth })`
 
 This is the channel the Ash dev client and any deployed-agent SDK talk to — it mounts the routes
-under `/ash/v1/session*` documented in [`../../external-agent-protocol.md`](../../external-agent-protocol.md).
+under `/ash/v1/session*` documented in [Ash External Agent Protocol](../../external-agent-protocol.md).
 
 It requires an auth function. Use `experimental-ash/channels/auth` for the common helpers such as
 `vercelOidc()`, `httpBasic()`, and `none()`.
@@ -208,7 +208,7 @@ Each compiles down to the one below it:
 - `slackChannel(config)` -> `defineChannel` + Chat SDK setup + typed event dispatch
 - `defineChannel` -> the primitive
 
-For a Slack app backed by Vercel Connex, see [`./slack.md`](./slack.md) to create the Connex client
+For a Slack app backed by Vercel Connex, see [Slack channel setup](./slack.md) to create the Connex client
 and channel file.
 
 ## File Uploads
@@ -251,9 +251,9 @@ at send time.
 
 ## What To Read Next
 
-- [`./slack.md`](./slack.md)
-- [`./attachments.md`](./attachments.md)
-- [`../project-layout.md`](../project-layout.md)
-- [`../typescript-api.md`](../typescript-api.md)
-- [`../auth-and-route-protection.md`](../auth-and-route-protection.md)
-- [`../../external-agent-protocol.md`](../../external-agent-protocol.md)
+- [Slack channel setup](./slack.md)
+- [Channel attachments](./attachments.md)
+- [Project Layout](../project-layout.md)
+- [TypeScript API](../typescript-api.md)
+- [Auth And Route Protection](../auth-and-route-protection.md)
+- [Ash External Agent Protocol](../../external-agent-protocol.md)

package/dist/docs/public/cli-build-and-debugging.md

@@ -80,6 +80,6 @@ When something is wrong:
 
 ## What To Read Next
 
-- [`project-layout.md`](./project-layout.md)
-- [`runs-and-streaming.md`](./runs-and-streaming.md)
-- [`typescript-api.md`](./typescript-api.md)
+- [Project Layout](./project-layout.md)
+- [Sessions And Streaming](./runs-and-streaming.md)
+- [TypeScript API](./typescript-api.md)

package/dist/docs/public/connections.md

@@ -124,7 +124,7 @@ when it needs a different cache and principal model:
   (status pages, shared dashboards, system bots).
 
 Ash resolves the active principal before every authorization call. See
-[`session-context.md`](./session-context.md) for how the principal flows through the runtime.
+[Session Context](./session-context.md) for how the principal flows through the runtime.
 
 ## Headers
 
@@ -157,7 +157,7 @@ export default defineMcpClientConnection({
 ```
 
 `never()` allows all calls, `once()` requires approval the first time per session, `always()`
-requires approval every time. See [`human-in-the-loop.md`](./human-in-the-loop.md) for the approval
+requires approval every time. See [Human In The Loop](./human-in-the-loop.md) for the approval
 runtime.
 
 ## Tool Filters
@@ -177,6 +177,6 @@ Tools that don't pass the filter are silently excluded from `connection_search`.
 
 ## What To Read Next
 
-- [`tools.md`](./tools.md) — authored tools live alongside connection-provided tools.
-- [`human-in-the-loop.md`](./human-in-the-loop.md) — interactive consent and approval runtime.
-- [`session-context.md`](./session-context.md) — how the active principal flows through the runtime.
+- [Tools](./tools.md) — authored tools live alongside connection-provided tools.
+- [Human In The Loop](./human-in-the-loop.md) — interactive consent and approval runtime.
+- [Session Context](./session-context.md) — how the active principal flows through the runtime.

package/dist/docs/public/context-control.md

@@ -88,7 +88,7 @@ prompt.
 - flat markdown skills may omit frontmatter
 - tools stay visible whether or not a skill is activated
 
-See [`skills.md`](./skills.md) for the full authoring model and install notes.
+See [Skills](./skills.md) for the full authoring model and install notes.
 
 ## 4. Put Runtime Files In The Workspace, Not The Prompt
 
@@ -102,7 +102,7 @@ Today that mainly means:
 - skill files are available under the active runtime workspace root
 - the model can inspect them with the shared `bash` tool
 
-See [`workspace.md`](./workspace.md) and [`sandbox.md`](./sandbox.md).
+See [Workspace](./workspace.md) and [Sandboxes](./sandbox.md).
 
 ## 5. Delegate To A Specialist With A Subagent
 
@@ -115,7 +115,7 @@ Subagents are a context-control tool too:
 - they can have their own tools and their own sandbox
 - they run inside their own delegated subagent context instead of extending the root agent inline
 
-See [`subagents.md`](./subagents.md).
+See [Subagents](./subagents.md).
 
 ## Choosing The Right Lever
 
@@ -139,8 +139,8 @@ For most agents:
 
 ## What To Read Next
 
-- [`tools.md`](./tools.md)
-- [`hooks.md`](./hooks.md)
-- [`skills.md`](./skills.md)
-- [`workspace.md`](./workspace.md)
-- [`subagents.md`](./subagents.md)
+- [Tools](./tools.md)
+- [Hooks](./hooks.md)
+- [Skills](./skills.md)
+- [Workspace](./workspace.md)
+- [Subagents](./subagents.md)

package/dist/docs/public/evals.md

@@ -287,6 +287,6 @@ For most apps:
 
 ## What To Read Next
 
-- [`typescript-api.md`](./typescript-api.md)
-- [`tools.md`](./tools.md)
-- [`runs-and-streaming.md`](./runs-and-streaming.md)
+- [TypeScript API](./typescript-api.md)
+- [Tools](./tools.md)
+- [Sessions And Streaming](./runs-and-streaming.md)

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

@@ -157,8 +157,8 @@ curl -X POST http://127.0.0.1:3000/ash/v1/session/<sessionId> \
 
 ## What To Read Next
 
-- [`project-layout.md`](./project-layout.md) for every supported authored slot
-- [`agent-ts.md`](./agent-ts.md) for runtime config
-- [`skills.md`](./skills.md) for on-demand procedures
-- [`tools.md`](./tools.md) for typed integrations
-- [`runs-and-streaming.md`](./runs-and-streaming.md) for the durable session model
+- [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
+- [Sessions And Streaming](./runs-and-streaming.md) for the durable session model

package/dist/docs/public/hooks.md

@@ -230,7 +230,7 @@ when both are registered.
 
 ## What to read next
 
-- [`tools.md`](./tools.md)
-- [`context-control.md`](./context-control.md)
-- [`runs-and-streaming.md`](./runs-and-streaming.md)
-- [`session-context.md`](./session-context.md)
+- [Tools](./tools.md)
+- [Context Control](./context-control.md)
+- [Sessions And Streaming](./runs-and-streaming.md)
+- [Session Context](./session-context.md)

package/dist/docs/public/human-in-the-loop.md

@@ -249,6 +249,6 @@ If you press `Escape` and then send a normal message, the pending requests are i
 
 ## What To Read Next
 
-- [`agent-ts.md`](./agent-ts.md)
-- [`tools.md`](./tools.md)
-- [`runs-and-streaming.md`](./runs-and-streaming.md)
+- [`agent.ts`](./agent-ts.md)
+- [Tools](./tools.md)
+- [Sessions And Streaming](./runs-and-streaming.md)

package/dist/docs/public/instrumentation.md

@@ -36,7 +36,8 @@ telemetry -- there is no separate `isEnabled` toggle.
 
 The `setup` callback is invoked by the framework at server startup with the resolved agent name. Use
 it to register your OTel provider (e.g. `registerOTel` from `@vercel/otel`). The
-`context.agentName` value comes from `defineAgent`, so you never need to hard-code a service name.
+`context.agentName` is derived from the agent's filesystem path at compile time, so you never need
+to hard-code a service name.
 
 Any OTel-compatible backend works (Braintrust, Honeycomb, Datadog, Jaeger). Install the exporter
 package you need and configure it in the callback.
@@ -73,5 +74,5 @@ calls and tool executions are traced automatically. Session context (`ash.versio
 
 ## What To Read Next
 
-- [`agent-ts.md`](./agent-ts.md)
-- [`project-layout.md`](./project-layout.md)
+- [`agent.ts`](./agent-ts.md)
+- [Project Layout](./project-layout.md)