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

package/docs/internals/context.md

@@ -1,126 +1,302 @@
 # Unified Context
 
-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.
+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.
 
-## Core Model
+## Files To Read
 
-Ash now has two key categories:
+- `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`
 
-- `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.
+## Core Primitives
 
-`AshContext` exposes a uniform API:
+### ContextKey
+
+A typed key identifies a named context slot. Durable values written through `set()` are
+serialized at `"use step"` boundaries. Virtual provider output may also be read through the same
+key during a step.
+
+```ts
+class ContextKey<T> {
+  readonly name: string;
+  readonly codec?: {
+    serialize(value: T): unknown;
+    deserialize(data: unknown): T | Promise<T>;
+  };
+}
+```
+
+### Type Hierarchy
+
+The context type system is a single inheritance chain defined in `key.ts`:
+
+```
+ContextReader    { get, require, has }
+    ↑ extends
+ContextAccessor  { set, ensure }
+    ↑ extends
+AshContext        { entries() }
+```
+
+- `ContextReader` — read-only view for providers and codec deserialization
+- `ContextAccessor` — read/write view for channels (`onDeliver`) and authored code
+- `AshContext` — full container with the `entries()` iterator used by the serialization layer
+
+### AshContext / ContextContainer
+
+The container interface. One instance per execution scope. Reads see the virtual provider overlay
+first, then the durable map. Writes always target the durable map.
 
 ```ts
 interface AshContext {
-  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;
+  get<T>(key: ContextKey<T>): T | undefined;
+  require<T>(key: ContextKey<T>): T;
+  has<T>(key: ContextKey<T>): boolean;
+  set<T>(key: ContextKey<T>, value: T): T;
+  set<T>(key: ContextKey<T>, updater: (current: T | undefined) => T): T;
+  ensure<T>(key: ContextKey<T>, create: () => T): T;
 }
 ```
 
-Public helpers such as `getContext`, `setContext`, `ensureContext`, `getSession`, `getSandbox`, and
-`getSkill` all delegate to this container.
+The concrete implementation class is `ContextContainer` (in `container.ts`).
 
-## Durable Context Lifecycle
+### contextStorage
 
-Durable authored context no longer piggybacks on runtime seed serialization.
+The single `AsyncLocalStorage<AshContext>` instance. Only `runStep` and the runtime entry points
+call `contextStorage.run(...)`. Everything else reads via `loadContext()`.
 
-Every step now follows this flow:
+### loadContext()
 
-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`.
+Returns the active `AshContext` from `contextStorage`, or throws. Authored code (tools, steps,
+model callbacks) uses this implicitly through the public accessors.
 
-The main files are:
+## Key Categories
 
-- `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`
+### Seed keys
+
+Set by the runtime entry point with live values. Serialized and deserialized at durable step
+boundaries via their codec.
 
-## Runtime Seed Serialization
+| 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 |
+| `ChannelKey` | `Channel` | serializes kind + state, deserializes by hydrating the correct channel class |
+| `BundleKey` | `CompiledBundle` | serializes to `compiledArtifactsSource`, deserializes via `getCompiledRuntimeAgentBundle` |
 
-`serializeRuntimeContext(...)` and `deserializeRuntimeContext(...)` only handle
-`RuntimeContextKey`s marked `serializable: true`.
+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.
 
-That includes seed values such as:
+### Virtual keys
 
-- auth and initiator auth
-- session id and continuation token
-- run mode
-- parent lineage
-- compiled bundle
-- serialized channel
+Created by providers during `runStep`. Never serialized — providers reconstruct them each step
+from durable context and the harness session.
 
-Durable authored context is intentionally excluded. `assertNoDurableContextInRuntimeSeed(...)`
-guards against leaking a public `ContextKey` into the runtime seed payload.
+| Key | Type | Provider |
+|-----|------|----------|
+| `SessionKey` | `Session` | `sessionProvider` |
+| `SandboxKey` | `SandboxAccess` | `sandboxProvider` |
+| `SkillKey` | `SkillAccess` | `skillProvider` |
 
 ## Providers
 
-Providers still reconstruct derived runtime values on each step:
+Public channel-scoped providers implement `ContextProvider<T>`:
+
+```ts
+interface ContextProvider<T> {
+  readonly key: ContextKey<T>;
+  create(ctx: ContextReader): T | undefined | Promise<T | undefined>;
+}
+```
+
+Public providers are derive-only. They run after `onDeliver()` and after the framework providers,
+so they can rebuild live step-local values from the visible context. Returning `undefined` means
+the provider is not active for this step.
+
+Framework internals use a superset contract (`FrameworkContextProvider`) that also receives the
+current harness session and may commit provider-owned session data after the step.
+
+Provider ordering matters. The framework providers are baked into `runStep` in dependency order:
+
+1. `sessionProvider` — depends only on durable seed keys
+2. `sandboxProvider` — depends on `BundleKey` and `SessionIdKey`
+3. `skillProvider` — depends on `BundleKey`
+4. channel-declared public providers — depend on whatever context is visible after `onDeliver()`
+
+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. Clears the previous step's virtual overlay.
+2. Builds framework virtual providers in order.
+3. Builds any channel-scoped public providers declared on the active channel class.
+4. Runs the callback inside `contextStorage.run(ctx, ...)` so authored code can read the context.
+5. After the callback completes, calls framework provider `commit` hooks for provider-owned
+   session state.
+
+## 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).
+
+The workflow runtime serializes the durable context once at `start()` time, then threads the latest
+serialized context forward after every durable step. Each `"use step"` boundary deserializes the
+durable map back, `onDeliver()` mutates it for the turn, and providers reconstruct virtual values.
+
+The channel codec is owned by the `ChannelKey` definition in `context/keys.ts`.
+Channel classes themselves have no knowledge of serialization.
+
+## Channel Context
+
+Auth is separate from the channel — it lives on `RunInput.auth` and `DeliverInput.auth`. There is
+no `ContextUpdater` callback, no `withAuth`/`withContext` wrappers, and no deliver-updater-registry
+side-channel.
+
+### Auth
+
+Auth lives on the run and deliver inputs, not on the channel itself:
+
+- `RunInput.auth` — the caller for the current run
+- `RunInput.initiatorAuth` — the caller that started the durable session (defaults to `auth` on root
+  runs; subagent passes the parent's initiator)
+
+The runtime reads `RunInput.auth` and `RunInput.initiatorAuth` when seeding `AuthKey` and
+`InitiatorAuthKey`. On `deliver()`, the runtime updates `AuthKey` from `DeliverInput.auth` so that
+`session.auth.current` reflects the follow-up caller while `session.auth.initiator` stays the same.
+
+### Custom context via `Channel.onDeliver`
+
+Channels set custom durable context keys inside `onDeliver(ctx, payload)`. The method receives a
+narrow `ContextAccessor` as its first argument (typed `get` / `require` / `has` /
+`set` / `ensure` with `ContextKey`) and returns a
+`Promise<StepInput>`. This runs once per turn — both the initial `run()` and each `deliver()` —
+after auth keys are seeded. Channel code stays workflow-agnostic because it only touches the
+accessor.
+
+```ts
+class TenantChannel extends Channel {
+  static readonly kind = "tenant-channel";
+
+  private readonly inner: Channel;
+  private readonly tenantId: string;
+
+  constructor(state: { readonly tenantId: string }) {
+    super();
+    this.tenantId = state.tenantId;
+    this.inner = new HttpChannel();
+  }
+
+  async onEvent(event) {
+    return await this.inner.onEvent(event);
+  }
+
+  async onDeliver(ctx, payload) {
+    ctx.set(TenantKey, this.tenantId);
+    return await this.inner.onDeliver(ctx, payload);
+  }
+
+  serialize() {
+    return { tenantId: this.tenantId };
+  }
+}
+```
+
+### Deliver path
+
+On `deliver()`, the channel is deserialized from the session (it was serialized at `run()` time via
+the `ChannelKey` codec). The runtime applies `DeliverInput.auth` to update the auth key, then calls
+`channel.onDeliver(ctx, payload)` on the deserialized channel. No process-local user registration or
+function stashing is needed because the runtime rebuilds the channel from the compiled bundle's
+channel registry plus the serialized channel state.
+
+### Files
 
-- `SessionKey` via `sessionProvider`
-- `SandboxKey` via `sandboxProvider`
-- `SkillKey` via `skillProvider`
+- `packages/ash/src/channel/types.ts` — `Channel`, `ContextAccessor` types
+- `packages/ash/src/execution/runtime-context.ts` — `buildRunContext` (reads `RunInput.auth`,
+  seeds auth keys)
+- `packages/ash/src/execution/workflow-steps.ts` — deserializes channel, applies deliver auth
+- `packages/ash/src/execution/continuous-entry.ts` — applies deliver auth on in-memory channel
 
-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 a `ContextContainer` via `buildRunContext` (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 a `ContextContainer` 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 `loadContext()`. Sandbox tools read `SandboxKey`;
+the `load_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 `loadContext()`:
 
-It prevents channels from becoming an untracked second session storage system.
+- `getContext(key)` returns `T | undefined`
+- `requireContext(key)` returns `T` or throws
+- `hasContext(key)` returns `boolean`
+- `setContext(key, value | updater)` returns `T`
+- `ensureContext(key, factory)` returns `T`
 
-## Runtime Split
+- `getSession()` reads `SessionKey`
+- `getSandbox(name)` reads `SandboxKey`
+- `getSkill(identifier)` reads `SkillKey`
 
-Both runtime flavors now use the same context story:
+## What Was Removed
 
-- 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
+The unified context replaced these six prior mechanisms:
 
-That removes the old semantic split where in-memory runs behaved differently from durable workflow
-runs.
+- `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

package/docs/public/README.md

@@ -19,22 +19,21 @@ 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. [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)
+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)
 
 ## The Public Mental Model
 
@@ -57,11 +56,10 @@ Ash then gives you:
 - a stable HTTP message route
 - optional channel webhook routes
 - a reconnectable session stream
-- durable session context across turns
+- durable session state across turns
 - a shared runtime workspace
 - optional isolated sandboxes
-- typed runtime helpers such as `getSession()`, `getContext()`, `setContext()`, `ensureContext()`,
-  `getSandbox()`, and `getSkill()`
+- typed runtime helpers such as `getSession()`, `getSandbox()`, and `getSkill()`
 
 ## The Runtime Shape
 

package/docs/public/channels/README.md

@@ -9,7 +9,6 @@ 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.
@@ -87,8 +86,15 @@ 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`.
+When you extend `SlackChannel`, keep context flow in two stages:
+
+- write durable serializable facts in `onDeliver()`
+- declare live step-local values on `static readonly contextProviders = [...]`
+- read those values from tools and other authored step code with the unified context helpers
+
+`contextProviders` is discovered from the channel class, not the channel instance, and providers run
+after `onDeliver()` on each step. See [`session-context.md`](../session-context.md) for the full
+pattern.
 
 ## What To Read Next
 

package/docs/public/sandboxes.md

@@ -160,7 +160,7 @@ You can also bind a live sandbox directly from any authored runtime function (to
 callback) via `getSandbox`:
 
 ```ts
-import { getSandbox } from "experimental-ash";
+import { getSandbox } from "experimental-ash/sandboxes";
 import { defineTool } from "experimental-ash/tools";
 import { z } from "zod";