experimental-ash 0.2.0-alpha.2 → 0.2.0-alpha.21

package/docs/internals/context.md

@@ -1,206 +1,126 @@
 # Unified Context
 
-Ash uses a single `AshContext` container, bound by one `AsyncLocalStorage` instance, to carry all
-runtime state through the execution stack. There are no secondary `AsyncLocalStorage` bindings, no
-custom dehydration protocols, and no out-of-band parameter passing for contextual data.
+Ash uses one `AshContext` container, bound by one `AsyncLocalStorage`, to carry all ambient runtime
+data through execution. There is no second authored-state channel and no separate dehydration path
+for public context.
 
-## Files To Read
+## Core Model
 
-- `packages/ash/src/context/key.ts`
-- `packages/ash/src/context/container.ts`
-- `packages/ash/src/context/provider.ts`
-- `packages/ash/src/context/keys.ts`
-- `packages/ash/src/context/serialize.ts`
-- `packages/ash/src/context/run-step.ts`
-- `packages/ash/src/context/accessors.ts`
-- `packages/ash/src/context/providers/session.ts`
-- `packages/ash/src/context/providers/sandbox.ts`
-- `packages/ash/src/context/providers/skill.ts`
+Ash now has two key categories:
 
-## Core Primitives
+- `ContextKey<T>`: public durable authored context. Values live on `session.context`.
+- `RuntimeContextKey<T>`: private framework-only runtime values. These seed one step and may be
+  reconstructed on the next step.
 
-### ContextKey
-
-A typed key identifies a value in the container. Keys that hold non-JSON-safe values declare a
-codec for serialization at `"use step"` boundaries.
-
-```ts
-class ContextKey<T> {
-  readonly name: string;
-  readonly codec?: {
-    serialize(value: T): unknown;
-    deserialize(data: unknown): T | Promise<T>;
-  };
-}
-```
-
-### AshContext
-
-The container interface. One instance per execution scope.
+`AshContext` exposes a uniform API:
 
 ```ts
 interface AshContext {
-  get<T>(key: ContextKey<T>): T;
-  tryGet<T>(key: ContextKey<T>): T | undefined;
-  has(key: ContextKey<unknown>): boolean;
-  set<T>(key: ContextKey<T>, value: T): void;
+  get<T>(key: ContextStoreKey<T>): T;
+  tryGet<T>(key: ContextStoreKey<T>): T | undefined;
+  has<T>(key: ContextStoreKey<T>): boolean;
+  set<T>(key: ContextStoreKey<T>, value: T): void;
+  ensure<T>(key: ContextStoreKey<T>, valueOrFactory: T | (() => T)): T;
 }
 ```
 
-### contextStorage
+Public helpers such as `getContext`, `setContext`, `ensureContext`, `getSession`, `getSandbox`, and
+`getSkill` all delegate to this container.
 
-The single `AsyncLocalStorage<AshContext>` instance. Only `runStep` and the runtime entry points
-call `contextStorage.run(...)`. Everything else reads via `requireContext()`.
+## Durable Context Lifecycle
 
-### requireContext()
+Durable authored context no longer piggybacks on runtime seed serialization.
 
-Returns the active `AshContext` from `contextStorage`, or throws. Authored code (tools, steps,
-model callbacks) uses this implicitly through the public accessors.
+Every step now follows this flow:
 
-## Key Categories
+1. Deserialize runtime seed keys with `deserializeRuntimeContext(...)`.
+2. Hydrate all registered public `ContextKey`s from `session.context`.
+3. Seed internal framework bookkeeping from `session.internal`.
+4. Apply deliver-time auth and run `channel.onDeliver(...)`.
+5. Run providers and step code inside `contextStorage.run(...)`.
+6. Commit the full durable context bag back to `session.context`.
 
-### Seed keys
+The main files are:
 
-Set by the runtime entry point with live values. Serialized and deserialized at durable step
-boundaries via their codec.
+- `packages/ash/src/context/serialize.ts`
+- `packages/ash/src/context/durable-context.ts`
+- `packages/ash/src/execution/step-context.ts`
+- `packages/ash/src/context/run-step.ts`
 
-| Key | Type | Codec |
-|-----|------|-------|
-| `AuthKey` | `SessionAuthContext \| null` | none (JSON-safe) |
-| `InitiatorAuthKey` | `SessionAuthContext \| null` | none |
-| `SessionIdKey` | `string` | none |
-| `RunIdKey` | `string` | none |
-| `ContinuationTokenKey` | `string` | none |
-| `ModeKey` | `RunMode` | none |
-| `NodeSelectorKey` | `string` | none — points at the active graph node (root or a delegated subagent selector) |
-| `ParentSessionKey` | `SessionParent` | none — set only on delegated child contexts to carry parent lineage |
-| `ChannelEmitterKey` | `ChannelEmitter` | serializes kind + state, deserializes by hydrating the correct emitter class |
-| `BundleKey` | `CompiledBundle` | serializes to `compiledArtifactsSource`, deserializes via `getCompiledRuntimeAgentBundle` |
+## Runtime Seed Serialization
 
-Keys self-register in a global registry at construction time. The serialization
-layer uses this registry to resolve string names back to typed keys — there is no
-explicit seed key list.
+`serializeRuntimeContext(...)` and `deserializeRuntimeContext(...)` only handle
+`RuntimeContextKey`s marked `serializable: true`.
 
-### Derived keys
+That includes seed values such as:
 
-Created by providers during `runStep`. Never serialized — providers reconstruct them each step
-from seed keys and the harness session.
+- auth and initiator auth
+- session id and continuation token
+- run mode
+- parent lineage
+- compiled bundle
+- serialized channel
 
-| Key | Type | Provider |
-|-----|------|----------|
-| `SessionKey` | `Session` | `sessionProvider` |
-| `SandboxKey` | `SandboxAccess` | `sandboxProvider` |
-| `SkillKey` | `SkillAccess` | `skillProvider` |
+Durable authored context is intentionally excluded. `assertNoDurableContextInRuntimeSeed(...)`
+guards against leaking a public `ContextKey` into the runtime seed payload.
 
 ## Providers
 
-Providers implement `ContextProvider<T>`:
-
-```ts
-interface ContextProvider<T> {
-  readonly key: ContextKey<T>;
-  create(ctx: AshContext, session: HarnessSession):
-    ProviderResult<T> | undefined | Promise<ProviderResult<T> | undefined>;
-  commit?(value: T, session: HarnessSession):
-    HarnessSession | Promise<HarnessSession>;
-}
-```
-
-`create` receives the context (with seed keys and earlier providers already set) and the current
-harness session. It returns a `ProviderResult` with the live value and optionally a modified
-session (e.g. skills enriching the system prompt). Returning `undefined` means the provider is not
-active for this step.
-
-`commit` is called after the step completes. It receives the live value (which may have been
-mutated during the step) and the harness session from the step result. It returns an updated
-session with any state changes persisted. Only providers with mutable state need this (sandbox
-snapshots, skill activations).
-
-Provider ordering matters. The framework providers are baked into `runStep` in dependency order:
-
-1. `sessionProvider` — depends only on seed keys
-2. `sandboxProvider` — depends on `BundleKey` and `SessionIdKey`
-3. `skillProvider` — depends on `BundleKey`
-
-There is no separate provider list to import — `runStep` knows its providers internally.
-
-## Step Runner
-
-`runStep` orchestrates the provider lifecycle around a step callback:
-
-1. Iterates providers in order — each may set its key on the context and optionally modify the
-   harness session.
-2. Runs the callback inside `contextStorage.run(ctx, ...)` so authored code can read the context.
-3. After the callback completes, iterates providers again to call `commit` hooks, persisting
-   mutable state back onto the session.
-
-## Serialization At Step Boundaries
-
-`serializeContext` and `deserializeContext` handle durable step boundaries generically.
-`serializeContext` iterates all entries in the context, calling each codec-backed key's codec
-when present. `deserializeContext` iterates the plain JSON record
-and resolves each string name back to its registered `ContextKey` via the global key registry.
-Keys without a codec are stored as-is (they must be JSON-safe).
+Providers still reconstruct derived runtime values on each step:
 
-The workflow runtime serializes the context once at `start()` time. Each `"use step"` boundary
-deserializes it back, then providers reconstruct derived values.
+- `SessionKey` via `sessionProvider`
+- `SandboxKey` via `sandboxProvider`
+- `SkillKey` via `skillProvider`
 
-The channel emitter codec is owned by the `ChannelEmitterKey` definition in `context/keys.ts`.
-Emitter classes themselves have no knowledge of serialization.
+These are runtime-only values, so they use `RuntimeContextKey`, not public `ContextKey`.
 
-## Integration Points
+Provider-owned mutable state stays separate from authored durable context:
 
-### Runtime entry (workflow)
+- durable authored values live on `session.context`
+- internal framework bookkeeping lives on `session.internal`
+- provider snapshots such as `sandboxState` stay on their dedicated session fields
 
-`workflow-runtime.ts` builds an `AshContextImpl` via `createRootContext` (for `run()`) or
-`createDelegatedChildContext` (for `delegate()`), sets seed keys, serializes, and passes
-`serializedContext` to `workflowEntry` via `start()`. The ambient runtime is registered at
-this point so durable steps can later recover it via `tryGetAmbientWorkflowRuntime()`.
+## Channel Setup
 
-### Runtime entry (continuous)
+`packages/ash/src/execution/step-context.ts` owns the pre-step channel path for both runtimes:
 
-`continuous-runtime.ts` builds an `AshContextImpl` via the same two helpers and passes the
-live context directly to `runStep` (no serialization needed since there are no durable step
-boundaries). `RuntimeKey` is attached to the context once at run creation.
+1. rebuild the fresh step context
+2. hydrate durable context
+3. seed pending input request bookkeeping
+4. apply deliver-time auth
+5. call `channel.onDeliver(ctx, payload)`
+6. assert that serialized channel state did not change
 
-### Delegation
+That ordering matters. `onDeliver(...)` runs after durable context hydration, so channel-seeded
+context cannot be overwritten by later hydration.
 
-`runtime.delegate(input)` starts a child run rooted at a non-root graph node. Its
-`DelegateInput` extends `RunInput` and adds `parent: SessionParent` and
-`target: { selector }`. `createDelegatedChildContext` seeds the child context with the
-forwarded initiator auth, the delegate's current auth, the parent lineage, the child node
-selector, and the child's own run/session identifiers. The subagent tool wrapper in
-`execution/subagent-tool.ts` is the sole in-tree caller of `delegate()`.
+## Channel State Rule
 
-### Durable step boundary
+Serialized channel state is immutable after the run starts.
 
-`workflow-steps.ts` deserializes the context from the serialized record, attaches the ambient
-workflow runtime via `RuntimeKey` (when one is registered), resolves the active graph node
-from `NodeSelectorKey`, and calls `runStep` with the framework providers.
+The runtime snapshots `channel.serialize()` before `onDeliver(...)` and again after step execution.
+If the serialized shape changes, the runtime throws with guidance to move that data into:
 
-### Tool executors
+- durable context when authored code needs it across turns
+- internal `session.internal` when only framework bookkeeping needs it
 
-Tool executors read from the container via `requireContext()`. Sandbox tools read `SandboxKey`;
-the `activate_skill` action reads `SkillKey`. Authored tools access context through the public
-accessors (`getSession`, `getSandbox`, etc.).
+This keeps channel responsibilities narrow:
 
-### Public API
+- transport normalization
+- continuation token ownership
+- per-turn context seeding
+- delivery policy
 
-The public accessors in `context/accessors.ts` delegate to `requireContext()`:
+It prevents channels from becoming an untracked second session storage system.
 
-- `getSession()` reads `SessionKey`
-- `getSandbox(name)` reads `SandboxKey`
-- `getSkill(identifier)` reads `SkillKey`
+## Runtime Split
 
-## What Was Removed
+Both runtime flavors now use the same context story:
 
-The unified context replaced these six prior mechanisms:
+- workflow runtime stores runtime seed keys once, then rebuilds a fresh step context on every
+  durable step
+- continuous runtime also rebuilds a fresh step context on every step, even though the process is
+  still live
 
-- `execution/runtime-context.ts` — execution-layer `AsyncLocalStorage` and `RuntimeContext`
-- `runtime/session-context.ts` — runtime-layer `AsyncLocalStorage` and `AuthoredRuntimeContext`
-- `execution/framework-context.ts` — `FrameworkContext`, `Dehydratable`, channel emitter
-  dehydration
-- `execution/context.ts` — `StepExecutionContext`, `ManagedRuntimeContext`, incremental context
-  assembly
-- The `Dehydratable` interface on channel emitters (replaced by key codecs)
-- Separate `session` parameter threading through tool executors and action handlers
+That removes the old semantic split where in-memory runs behaved differently from durable workflow
+runs.

package/docs/internals/message-runtime.md

@@ -5,10 +5,8 @@ channel-harness-runtime path. The old message-workflow and runtime-harness stack
 
 ## Files To Read
 
-- `packages/ash/src/internal/nitro/routes/message.ts`
-- `packages/ash/src/internal/nitro/routes/run-stream.ts`
+- `packages/ash/src/public/channels/http.ts`
 - `packages/ash/src/runtime/governance/auth/route-auth.ts`
-- `packages/ash/src/channel/http.ts`
 - `packages/ash/src/channel/types.ts`
 - `packages/ash/src/harness/tool-loop.ts`
 - `packages/ash/src/harness/types.ts`
@@ -21,7 +19,7 @@ channel-harness-runtime path. The old message-workflow and runtime-harness stack
 
 - `GET /.well-known/ash/v1/health`
 - `POST /.well-known/ash/v1/message`
-- `GET /.well-known/ash/v1/runs/:runId/stream`
+- `GET /.well-known/ash/v1/sessions/:sessionId/stream`
 
 The route prefix stays `v1`. What changed is the runtime behind it.
 
@@ -44,12 +42,12 @@ See [`context.md`](./context.md) for the full model.
 
 1. Nitro route auth validates the caller in `route-auth.ts`.
 2. `message.ts` parses either `{ message }` or `{ continuationToken, message }`.
-3. `channel/http.ts` derives a continuation token and provides an `EventHandler`.
+3. The HTTP channel derives a continuation token and owns event delivery via `onEvent`.
 4. The channel calls `runtime.run(...)` or `runtime.deliver(...)`.
 5. The runtime creates or reloads the durable session and invokes the shared harness step.
 6. The harness returns `{ session, next }`.
-7. The runtime persists the updated session, follows `next`, and streams events under the run id.
-8. Clients read the durable run through `GET /.well-known/ash/v1/runs/:runId/stream`.
+7. The runtime persists the updated session, follows `next`, and streams events under the session id.
+8. Clients read the durable session through `GET /.well-known/ash/v1/sessions/:sessionId/stream`.
 
 ## Start And Follow-Up Requests
 
@@ -69,22 +67,22 @@ Important behavior:
 
 - New starts return `202 Accepted`.
 - Start responses include `sessionId` and `continuationToken` in the JSON body.
-- Start responses also include `x-ash-run-id` and `location` headers so clients know which run to
-  stream.
+- Start responses also include `x-ash-session-id` and `location` headers so clients know which
+  session to stream.
 - Follow-up requests return `200 OK` with the same `continuationToken`.
-- `runId` remains the stream handle, but it is no longer the resume handle.
+- `sessionId` is the stream handle; `continuationToken` is the resume handle.
 
 ## Stream Contract
 
-`run-stream.ts` reads the durable workflow run directly from the workflow runtime and returns the
-canonical NDJSON stream.
+The stream channel reads the durable workflow session directly from the workflow runtime and returns
+the canonical NDJSON stream.
 
 Important behavior:
 
 - `startIndex` reconnects by event count.
-- Stream headers always include `x-ash-run-id`, `x-ash-stream-format`, `x-ash-stream-version`, and
+- Stream headers always include `x-ash-session-id`, `x-ash-stream-format`, `x-ash-stream-version`, and
   `x-ash-workflow-id`.
-- The stream route does not know about continuation tokens. It only needs the durable `runId`.
+- The stream route does not know about continuation tokens. It only needs the durable `sessionId`.
 
 ## Event Delivery
 
@@ -93,8 +91,8 @@ The runtime owns stream plumbing, but the channel owns delivery policy.
 Important behavior:
 
 - the runtime composes a raw stream writer from `getWritable()`
-- the channel contributes `EventHandler.onEvent(event, emit)`
-- the composed `emit` function is injected into the harness
+- the runtime calls `channel.onEvent(event)` for each lifecycle event; the channel returns the
+  (possibly transformed) event and may perform platform side effects before returning
 - the harness emits lifecycle events without knowing whether they go to HTTP, Slack, both, or
   neither
 
@@ -105,9 +103,10 @@ format.
 
 The current stream surface is:
 
-- `run.started`
+- `session.started`
 - `turn.started`
 - `message.received`
+- `step.started`
 - `sandbox.initialized`
 - `sandbox.restored`
 - `sandbox.command`
@@ -116,18 +115,21 @@ The current stream surface is:
 - `subagent.started`
 - `subagent.event`
 - `subagent.completed`
-- `thinking.completed`
+- `reasoning.completed`
 - `message.completed`
+- `step.completed`
 - `turn.completed`
+- `step.failed`
+- `turn.failed`
 - `session.waiting`
-- `run.completed`
-- `run.failed`
+- `session.completed`
+- `session.failed`
 
-`message.completed.data.finishReason` carries the assistant step outcome.
-`tool-calls` means the turn is continuing through tool execution; other values
-are terminal for the current turn.
+`message.completed.data.finishReason` remains available for message-level
+consumers. `step.completed.data.finishReason` mirrors the model-step outcome,
+and `tool-calls` means the turn is continuing through tool execution.
 
-Subagent activity is now inline on the parent run stream. There is no separate legacy child-workflow
+Subagent activity is now inline on the parent session stream. There is no separate legacy child-workflow
 stream path.
 
 ## Auth Boundary
@@ -139,7 +141,7 @@ Important behavior:
 - If both `auth` and `network` are omitted, the routes are open.
 - If only `network` is configured, the caller must pass the IP allow list.
 - If `auth` is configured, the caller must satisfy one configured strategy.
-- There is still no separate per-run ownership ACL after route auth succeeds.
+- There is still no separate per-session ownership ACL after route auth succeeds.
 
 The runtime stores both `auth.current` and `auth.initiator`. A later authenticated follow-up message
 may replace `auth.current` without rewriting the original initiator snapshot.
@@ -153,5 +155,5 @@ The current ownership split is:
 - The harness owns model/tool work and the `next` decision.
 - Execution/runtime owns durable workflow entry, persistence, and event-stream plumbing.
 - Clients keep both identifiers:
-  - `runId` for streaming
+  - `sessionId` for streaming
   - `continuationToken` for the next user message

package/docs/public/README.md

@@ -19,21 +19,22 @@ Read in this order:
 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. [workspace.md](./workspace.md)
-9. [sandboxes.md](./sandboxes.md)
-10. [channels/README.md](./channels/README.md)
-11. [human-in-the-loop.md](./human-in-the-loop.md)
-12. [session-context.md](./session-context.md)
-13. [runs-and-streaming.md](./runs-and-streaming.md)
-14. [subagents.md](./subagents.md)
-15. [schedules.md](./schedules.md)
-16. [evals.md](./evals.md)
-17. [auth-and-route-protection.md](./auth-and-route-protection.md)
-18. [vercel-deployment.md](./vercel-deployment.md)
-19. [cli-build-and-debugging.md](./cli-build-and-debugging.md)
+5. [migration-guide.md](./migration-guide.md)
+6. [context-control.md](./context-control.md)
+7. [skills.md](./skills.md)
+8. [tools.md](./tools.md)
+9. [workspace.md](./workspace.md)
+10. [sandboxes.md](./sandboxes.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)
 
 ## The Public Mental Model
 
@@ -55,11 +56,12 @@ Ash then gives you:
 
 - a stable HTTP message route
 - optional channel webhook routes
-- a reconnectable run stream
-- durable session state across turns
+- a reconnectable session stream
+- durable session context across turns
 - a shared runtime workspace
 - optional isolated sandboxes
-- typed runtime helpers such as `getSession()`, `getSandbox()`, and `getSkill()`
+- typed runtime helpers such as `getSession()`, `getContext()`, `setContext()`, `ensureContext()`,
+  `getSandbox()`, and `getSkill()`
 
 ## The Runtime Shape
 
@@ -73,13 +75,13 @@ know:
 That is why Ash exposes two identifiers:
 
 - `continuationToken` for the next user message
-- `runId` for streaming and inspection
+- `sessionId` for streaming and inspection
 
 ## How To Use These Docs
 
 - Start with the authored filesystem shape and `agent.ts`.
 - Then add runtime surfaces in this order: skills, tools, workspace, sandboxes, channels.
-- Then learn the durable runtime model: HITL, session context, runs, streaming, and
+- Then learn the durable runtime model: HITL, session context, sessions, streaming, and
   continuation-token follow-ups.
 - Then add advanced features: subagents, schedules, route protection, deployment.
 

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

@@ -9,16 +9,16 @@ These settings apply to:
 
 - `GET /.well-known/ash/v1/health`
 - `POST /.well-known/ash/v1/message`
-- `GET /.well-known/ash/v1/runs/:runId/stream`
+- `GET /.well-known/ash/v1/sessions/:sessionId/stream`
 
 ## The Main API
 
 ```ts
 // agent/channels/.well-known/ash/v1/message.ts
-import { httpMessageChannel } from "experimental-ash/channels/http";
+import { httpRoute } from "experimental-ash/channels/http";
 import { vercelOidc } from "experimental-ash/channels/auth";
 
-export default httpMessageChannel({
+export default httpRoute({
   auth: vercelOidc(),
 });
 ```
@@ -26,10 +26,10 @@ export default httpMessageChannel({
 For open routes, use `none()` explicitly:
 
 ```ts
-import { httpMessageChannel } from "experimental-ash/channels/http";
+import { httpRoute } from "experimental-ash/channels/http";
 import { none } from "experimental-ash/channels/auth";
 
-export default httpMessageChannel({
+export default httpRoute({
   auth: none(),
 });
 ```
@@ -96,27 +96,31 @@ Inside runtime code, `getSession().auth` gives you the caller snapshot.
 Important behavior:
 
 - `auth.current` is the caller for the active inbound turn
-- `auth.initiator` is the caller that started the durable run
-- authenticated follow-up messages can change `auth.current` without changing `auth.initiator`
+- `auth.initiator` is the caller that started the durable session
+- follow-up messages update `auth.current` without changing `auth.initiator`
 - unprotected agents expose both as `null`
 
+Auth on follow-up messages (`deliver()`) is honored by both the workflow and continuous runtimes.
+When a different user sends a follow-up to the same session, `session.auth.current` reflects the
+new caller on that turn while `session.auth.initiator` stays the same.
+
 ## What Ash Does Not Do
 
-Ash does not add a second run-ownership ACL layer on top of route auth.
+Ash does not add a second session-ownership ACL layer on top of route auth.
 
 In practice that means:
 
 - route access is governed at the HTTP boundary
 - the durable session keeps the caller snapshot for authored runtime use
-- there is no separate per-run ownership list you manage later
+- there is no separate per-session ownership list you manage later
 
 ## Example: Basic Auth Request
 
 ```ts
-import { httpMessageChannel } from "experimental-ash/channels/http";
+import { httpRoute } from "experimental-ash/channels/http";
 import { httpBasic } from "experimental-ash/channels/auth";
 
-export default httpMessageChannel({
+export default httpRoute({
   auth: httpBasic({
     username: "ops",
     password: process.env.ROUTE_AUTH_BASIC_PASSWORD,
@@ -129,4 +133,3 @@ export default httpMessageChannel({
 - [`agent-ts.md`](./agent-ts.md)
 - [`session-context.md`](./session-context.md)
 - [`vercel-deployment.md`](./vercel-deployment.md)
-

package/docs/public/channels/README.md

@@ -9,6 +9,7 @@ Channels are the transport layer in Ash's channel-harness-runtime split. A chann
 - deriving or resuming the stable `continuationToken`
 - applying route auth and network policy
 - deciding how runtime events are delivered back to the platform
+- seeding per-turn durable context inside `onDeliver(...)`
 
 The runtime and harness still own the model turn, tool execution, compaction, and session
 persistence.
@@ -17,8 +18,8 @@ persistence.
 
 Ash ships the public HTTP protocol as channels:
 
-- `httpMessageChannel()` for `POST /.well-known/ash/v1/message`
-- `httpRunStreamChannel()` for `GET /.well-known/ash/v1/runs/:runId/stream`
+- `httpRoute()` for `POST /.well-known/ash/v1/message`
+- `httpRunStreamRoute()` for `GET /.well-known/ash/v1/sessions/:sessionId/stream`
 
 Ash also supports authored channels under `agent/channels/` for platform-specific integrations such
 as Slack or custom webhooks.
@@ -43,9 +44,9 @@ Rules that matter:
 ## The Main API
 
 ```ts
-import { defineChannel } from "experimental-ash";
+import { defineRoute } from "experimental-ash";
 
-export default defineChannel({
+export default defineRoute({
   method: "POST",
   async fetch() {
     return new Response("ok");
@@ -53,30 +54,32 @@ export default defineChannel({
 });
 ```
 
-`defineChannel(...)` keeps the public surface Ash-owned and platform-specific only where necessary.
+`defineRoute(...)` defines a route — the HTTP request handler that receives webhooks and calls
+`agent.run()` or `agent.deliver()`. The route constructs a `Channel` (the conduit that owns auth,
+events, delivery, context, and serialization) and passes it to the runtime.
 
 ## HTTP Channels
 
 The framework ships two HTTP helpers on `experimental-ash/channels/http`:
 
-- `httpMessageChannel({ auth })`
-- `httpRunStreamChannel({ auth })`
+- `httpRoute({ auth })`
+- `httpRunStreamRoute({ auth })`
 
 Both require an auth function. Use `experimental-ash/channels/auth` for the common helpers such as
 `vercelOidc()`, `httpBasic()`, and `none()`.
 
 ```ts
-import { httpMessageChannel } from "experimental-ash/channels/http";
+import { httpRoute } from "experimental-ash/channels/http";
 import { vercelOidc } from "experimental-ash/channels/auth";
 
-export default httpMessageChannel({
+export default httpRoute({
   auth: vercelOidc(),
 });
 ```
 
 ## Slack And Other Authored Channels
 
-Authored channels can wrap those helpers or build custom transport flows with `defineChannel(...)`.
+Authored channels can wrap those helpers or build custom transport flows with `defineRoute(...)`.
 
 Use a custom channel when you want:
 
@@ -84,10 +87,12 @@ Use a custom channel when you want:
 - transport-specific delivery behavior
 - custom request parsing before the runtime turn starts
 
+Channel constructor state is for stable serialized transport identity only. Once a run starts, keep
+that state immutable and move mutable per-session data into durable context or `session.internal`.
+
 ## What To Read Next
 
 - [`../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)
-