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

package/docs/public/session-context.md

@@ -1,13 +1,15 @@
 # Session Context
 
-Ash exposes six runtime helpers for authored code:
+Ash exposes runtime helpers for authored code:
 
 - `getSession()`
-- `getContext(key)`
-- `setContext(key, value)`
-- `ensureContext(key, valueOrFactory)`
 - `getSandbox(name)`
 - `getSkill(identifier)`
+- `getContext(key)` — returns `T | undefined`
+- `requireContext(key)` — returns `T`, throws if unset
+- `hasContext(key)` — returns `boolean`
+- `setContext(key, valueOrUpdater)` — returns `T`
+- `ensureContext(key, factory)` — returns `T`
 
 These APIs work only inside active authored runtime execution such as tools and other Ash-invoked
 callbacks. Under the hood, they read from a single `AshContext` container that the framework binds
@@ -96,32 +98,11 @@ Important behavior:
 
 See [`skills.md`](./skills.md) for the full authoring model.
 
-## Durable Authored Context
-
-`ContextKey` values are session-durable by default. Once authored code sets a key, Ash hydrates it
-from `session.context` before later steps and commits it back after each step.
-
-```ts
-import { ContextKey, ensureContext, getContext, setContext } from "experimental-ash";
-
-const TenantKey = new ContextKey<string>("myapp.tenant");
-const NotesKey = new ContextKey<{ readonly notes: readonly string[] }>("myapp.notes");
-
-const tenant = getContext(TenantKey);
-const notes = ensureContext(NotesKey, () => ({ notes: [] }));
-
-setContext(NotesKey, {
-  notes: [...notes.notes, `Handled tenant ${tenant}`],
-});
-```
-
-Use `ensureContext` when a key needs a default value. `ContextKey({ initial })` no longer exists.
-
 ## Passing Custom Context From a Channel
 
-Channels can inject custom typed context into the agent inside `onDeliver`. This is useful when a
-channel needs to pass platform-specific metadata (tenant ID, feature flags, etc.) that authored
-tools can read.
+Channels can inject custom typed durable context into the agent inside `onDeliver`. This is useful
+when a channel needs to pass platform-specific metadata (tenant ID, feature flags, etc.) that
+authored tools can read on the same turn and on later turns.
 
 ### Defining a key
 
@@ -139,9 +120,8 @@ export const TenantKey = new ContextKey<string>("myapp.tenant");
 ### Setting context from a channel
 
 Wrap an existing channel with `onDeliver` to set custom context keys. The hook receives a narrow
-`ContextAccessor` (`get`, `tryGet`, `has`, `set`, `ensure`) as its first argument and a
-`DeliverPayload` as the second. It runs on both `run()` and `deliver()`, after Ash has hydrated the
-durable context bag for that turn.
+`ContextAccessor` (typed `get`/`set`) as its first argument and a `DeliverPayload` as the second. It
+runs on both `run()` and `deliver()`.
 
 `agent/channels/slack.ts`
 
@@ -167,8 +147,8 @@ class TenantSlackChannel extends SlackChannel<TenantSlackState> {
     });
   }
 
-  async onDeliver(ctx, payload) {
-    ctx.set(TenantKey, this.state().tenantId);
+  override async onDeliver(ctx, payload) {
+    ctx.set(TenantKey, this.state.tenantId);
     return await super.onDeliver(ctx, payload);
   }
 }
@@ -181,30 +161,96 @@ export default slackRoute({
 Auth lives on `RunInput.auth` and `DeliverInput.auth`, not on the channel object. There is no
 `withAuth` or `withContext` wrapper.
 
-Keep channel constructor state immutable after the run starts. Stable transport identity belongs in
-serialized channel state; mutable per-session data belongs in durable context or `session.internal`.
-
 ### Reading context from a tool
 
 ```ts
-import { getContext } from "experimental-ash";
+import { requireContext } from "experimental-ash";
 import { defineTool } from "experimental-ash/tools";
 import { TenantKey } from "../channels/keys.js";
 
 export default defineTool({
   description: "Return the active tenant.",
   async execute() {
-    const tenant = getContext(TenantKey);
+    const tenant = requireContext(TenantKey);
     return { tenant };
   },
 });
 ```
 
+### Rebuilding virtual values with `ContextProvider`
+
+If a channel needs to vend a live non-serializable object each step, declare a static
+`contextProviders` array on the channel class. This must be a class field such as
+`static readonly contextProviders = [...]`; the runtime reads providers from the channel class, not
+from the channel instance.
+
+For Slack subclasses, the intended pattern is:
+
+- `onDeliver()` writes durable serializable facts such as tenant IDs, channel IDs, or installation
+  IDs.
+- `static readonly contextProviders = [...]` derives live step-local values such as SDK clients
+  from those durable keys.
+- tools and other authored step code read the derived value with `requireContext(...)` or
+  `getContext(...)`.
+
+Providers run after `onDeliver()` and rebuild virtual values for the current step only, so
+`onDeliver()` should not expect provider output to exist yet.
+
+```ts
+import {
+  ContextKey,
+  type ContextProvider,
+} from "experimental-ash";
+import {
+  slackRoute,
+  SlackChannel,
+  type SlackChannelState,
+} from "experimental-ash/channels/slack";
+
+const TenantKey = new ContextKey<string>("myapp.tenant");
+const SlackClientKey = new ContextKey<{ readonly tenantId: string }>("myapp.slackClient");
+
+const slackClientProvider: ContextProvider<{ readonly tenantId: string }> = {
+  key: SlackClientKey,
+  create(ctx) {
+    return { tenantId: ctx.require(TenantKey) };
+  },
+};
+
+interface TenantSlackState extends SlackChannelState {
+  readonly tenantId: string;
+}
+
+class TenantSlackChannel extends SlackChannel<TenantSlackState> {
+  static override readonly kind = "tenant-slack";
+  static readonly contextProviders = [slackClientProvider];
+
+  constructor(state: SlackChannelState) {
+    super({
+      ...state,
+      tenantId: lookupTenant(state),
+    });
+  }
+
+  override async onDeliver(ctx, payload) {
+    ctx.set(TenantKey, this.state.tenantId);
+    return await super.onDeliver(ctx, payload);
+  }
+}
+
+export default slackRoute({
+  channel: TenantSlackChannel,
+});
+```
+
+Provider output is readable through `requireContext(SlackClientKey)` or
+`getContext(SlackClientKey)` during that step, but it is not serialized.
+
 ### Context on deliver
 
 `onDeliver` runs on every turn, including `deliver()` follow-ups. The channel is deserialized from
-the session, so its stable serialized state (including custom fields like `tenantId`) is available
-on follow-up turns.
+the session, so its state (including any custom fields like `tenantId`) is available on follow-up
+turns.
 
 Auth on `deliver()` is also honored — `session.auth.current` reflects the caller of each follow-up
 message, not just the session initiator. Deliver-time auth is passed via `DeliverInput.auth` and the
@@ -229,18 +275,18 @@ explaining the required scope.
 
 ## How It Works
 
-All runtime helpers read from the same `AshContext` container bound by a single
-`AsyncLocalStorage`. The framework sets up this context before invoking authored code:
+All three accessors read from the same `AshContext` container bound by a single `AsyncLocalStorage`.
+The framework sets up this context before invoking authored code:
 
-1. The runtime entry point creates an `AshContext` and serializes only runtime seed keys such as
-   auth, session id, channel, and compiled bundle.
-2. Before each step, Ash rebuilds a fresh context, hydrates durable authored context from
-   `session.context`, seeds runtime-only bookkeeping, and runs `channel.onDeliver(...)`.
-3. Providers create derived values such as session metadata, sandbox access, and skill access.
+1. The runtime entry point creates an `AshContext` and populates durable seed keys (auth, session
+   ID, channel, compiled bundle).
+2. `onDeliver()` can write durable authored context for the turn.
+3. Before each step, providers create virtual step-local values (session metadata, sandbox access,
+   skill access, channel-scoped live objects) from the current context.
 4. The step callback runs inside the `AsyncLocalStorage` scope, making the context available to
    all authored code in the call chain.
-5. After the step, Ash commits the full durable context bag back to `session.context` and lets
-   mutable providers persist any provider-owned state.
+5. After the step, framework providers with provider-owned mutable state (for example sandboxes)
+   commit those changes back onto the harness session.
 
 This lifecycle is fully managed by the framework. Authored code only needs to call the public
 accessors.

package/docs/public/tools.md

@@ -36,8 +36,8 @@ exposed to the model as `get_weather`; a file at `agent/tools/get-weather.ts` is
 `get-weather`. You can override that by setting `name` in the tool definition.
 
 `defineTool`, `disableTool`, `defineBashTool`, `defineReadFileTool`, and `defineWriteFileTool` live on the `experimental-ash/tools` subpath.
-Runtime helpers like `getSession`, `getContext`, `setContext`, `ensureContext`, `getSandbox`, and
-`getSkill` stay on the main `experimental-ash` barrel.
+Runtime helpers like `getSession`, `getSandbox`, `getSkill`, `getContext`, `requireContext`, `hasContext`, `setContext`, and `ensureContext` stay on the
+main `experimental-ash` barrel.
 
 ## What A Tool Definition Needs
 
@@ -106,8 +106,8 @@ execution surface by itself; executable behavior still comes from the tools the
 
 `read_file` reads a text file from the sandbox filesystem with line-numbered output. `write_file`
 writes a complete file, enforcing read-before-write for existing files and detecting stale reads.
-Both target the framework default sandbox. Compaction clears the durable read-file context so the
-model must re-read files before overwriting after compaction.
+Both target the framework default sandbox. Compaction clears the durable read-file state so the model
+must re-read files before overwriting after compaction.
 
 Authors can wrap, replace, or disable these defaults from `agent/tools/`.
 
@@ -225,23 +225,29 @@ export default defineWriteFileTool({
 ```
 
 When replacing the framework `read_file`, the authored version inherits the same compaction
-context-reset behavior by default. Provide an explicit `onCompact` to override that.
+state-reset behavior by default. Provide an explicit `onCompact` to override that.
 
 ### Replace A Default With Custom Context
 
-`agent/tools/todo.ts` - replace the framework `todo` tool with a custom durable-context version.
-Declare your own `ContextKey` and use `ensureContext` / `setContext` to read and write it:
+`agent/tools/todo.ts` - replace the framework `todo` tool with a custom durable context-backed
+version. Declare your own `ContextKey`, initialize it with `ensureContext`, and read/write it with
+`requireContext` / `setContext`:
 
 ```ts
-import { ContextKey, ensureContext, setContext } from "experimental-ash";
+import {
+  ContextKey,
+  ensureContext,
+  requireContext,
+  setContext,
+} from "experimental-ash";
 import { defineTool } from "experimental-ash/tools";
 import { z } from "zod";
 
-interface NoteListContext {
+interface NoteListState {
   readonly notes: readonly string[];
 }
 
-const NoteListContextKey = new ContextKey<NoteListContext>("myapp.notes");
+const NoteListStateKey = new ContextKey<NoteListState>("myapp.notes");
 
 export default defineTool({
   description: "Append a note or read the running list of notes.",
@@ -249,13 +255,15 @@ export default defineTool({
     note: z.string().optional(),
   }),
   async execute(input) {
+    ensureContext(NoteListStateKey, () => ({ notes: [] }));
+
     if (typeof input.note === "string" && input.note.length > 0) {
-      const current = ensureContext(NoteListContextKey, () => ({ notes: [] }));
-      setContext(NoteListContextKey, {
-        notes: [...current.notes, input.note],
-      });
+      const next = input.note;
+      setContext(NoteListStateKey, (current) => ({
+        notes: [...(current?.notes ?? []), next],
+      }));
     }
-    return ensureContext(NoteListContextKey, () => ({ notes: [] }));
+    return requireContext(NoteListStateKey);
   },
 });
 ```
@@ -263,8 +271,8 @@ export default defineTool({
 ### Subtleties Worth Knowing
 
 - The filename is the default name. There is also an explicit `name` property when you need it.
-- Durable context is owned by the replacement. Replacing `todo` with a fresh `defineTool` does not
-  inherit the framework's context key.
+- Context is owned by the replacement. Replacing `todo` with a fresh `defineTool` does not inherit
+  the framework's durable context key.
 - Authored-vs-authored collisions are impossible by construction. Two files cannot share a slug under
   the same `agent/tools/` directory.
 

package/docs/public/typescript-api.md

@@ -41,18 +41,16 @@ Most apps use `defineAgent`, `defineTool`, and `defineSandbox` the most.
 ## Runtime Helpers
 
 - `getSession()` - current session, turn, auth, and optional parent lineage
-- `getContext(key)` - read one durable authored context value
-- `setContext(key, value)` - write one durable authored context value
-- `ensureContext(key, valueOrFactory)` - read-or-create one durable context value
 - `getSandbox(name)` - live named sandbox session
 - `getSkill(identifier)` - handle for a named skill visible to the current agent
+- `getContext(key)` / `requireContext(key)` / `hasContext(key)` / `setContext(key)` / `ensureContext(key, factory)` - unified context helpers
 
 Related exported types:
 
 - `Session`, `SessionAuth`, `SessionAuthContext`, `SessionParent`, `SessionTurn`
 - `SkillHandle`, `SkillResource`
 - `RunMode`
-- `ContextKey`, `ContextKeyOptions`, `AshContext`
+- `ContextKey`, `ContextKeyOptions`, `ContextProvider`, `ContextReader`, `AshContext`
 - eval types from `experimental-ash/evals`
 
 Ash also exports lower-level runtime primitives such as `createToolLoopHarness(...)`,
@@ -63,8 +61,6 @@ sessions must finish inside the current invocation.
 
 These helpers only work inside active authored runtime execution.
 
-Breaking change details and before/after examples live in [`migration-guide.md`](./migration-guide.md).
-
 ## Markdown Helpers
 
 Ash also exports helpers for turning markdown into the same shapes as module-authored definitions:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-ash",
-  "version": "0.2.0-alpha.21",
+  "version": "0.2.0-alpha.22",
   "type": "module",
   "main": "./dist/src/index.js",
   "types": "./dist/src/index.d.ts",

package/dist/src/context/durable-context.d.ts

@@ -1,18 +0,0 @@
-import type { HarnessSession } from "../harness/types.js";
-import type { AshContext } from "./container.js";
-/**
- * Hydrates all durable context values from `session.context`.
- *
- * Unknown keys are ignored. Keys without a persisted value remain absent until
- * authored code or a channel explicitly sets or ensures them.
- */
-export declare function hydrateDurableContext(ctx: AshContext, session: HarnessSession): Promise<void>;
-/**
- * Serializes all durable context values currently set on the context.
- */
-export declare function serializeDurableContext(ctx: AshContext): Record<string, unknown>;
-/**
- * Commits the full durable context bag back to `session.context`.
- */
-export declare function commitDurableContext(ctx: AshContext, session: HarnessSession): HarnessSession;
-//# sourceMappingURL=durable-context.d.ts.map

package/dist/src/context/durable-context.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"durable-context.d.ts","sourceRoot":"","sources":["../../../src/context/durable-context.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAGjD;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,UAAU,EACf,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,IAAI,CAAC,CAef;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAYhF;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,cAAc,GAAG,cAAc,CAY7F"}

package/dist/src/context/durable-context.js

@@ -1,49 +0,0 @@
-import { isDeepStrictEqual } from "node:util";
-import { isDurableContextKey, resolveContextKey } from "./key.js";
-/**
- * Hydrates all durable context values from `session.context`.
- *
- * Unknown keys are ignored. Keys without a persisted value remain absent until
- * authored code or a channel explicitly sets or ensures them.
- */
-export async function hydrateDurableContext(ctx, session) {
-    const data = session.context ?? {};
-    for (const [name, raw] of Object.entries(data)) {
-        if (raw === undefined) {
-            continue;
-        }
-        const key = resolveContextKey(name);
-        if (key === undefined) {
-            continue;
-        }
-        ctx.set(key, key.codec ? await key.codec.deserialize(raw, ctx) : raw);
-    }
-}
-/**
- * Serializes all durable context values currently set on the context.
- */
-export function serializeDurableContext(ctx) {
-    const data = {};
-    for (const [key, value] of ctx.entries()) {
-        if (!isDurableContextKey(key) || value === undefined) {
-            continue;
-        }
-        data[key.name] = key.codec ? key.codec.serialize(value) : value;
-    }
-    return data;
-}
-/**
- * Commits the full durable context bag back to `session.context`.
- */
-export function commitDurableContext(ctx, session) {
-    const nextContext = serializeDurableContext(ctx);
-    const currentContext = session.context ?? {};
-    if (isDeepStrictEqual(nextContext, currentContext)) {
-        return session;
-    }
-    return {
-        ...session,
-        context: Object.keys(nextContext).length > 0 ? nextContext : undefined,
-    };
-}
-//# sourceMappingURL=durable-context.js.map

package/dist/src/context/durable-context.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"durable-context.js","sourceRoot":"","sources":["../../../src/context/durable-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAI9C,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAElE;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,GAAe,EACf,OAAuB;IAEvB,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;IAEnC,KAAK,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/C,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,SAAS;QACX,CAAC;QAED,MAAM,GAAG,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,SAAS;QACX,CAAC;QAED,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACxE,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAe;IACrD,MAAM,IAAI,GAA4B,EAAE,CAAC;IAEzC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC;QACzC,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACrD,SAAS;QACX,CAAC;QAED,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAClE,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAe,EAAE,OAAuB;IAC3E,MAAM,WAAW,GAAG,uBAAuB,CAAC,GAAG,CAAC,CAAC;IACjD,MAAM,cAAc,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;IAE7C,IAAI,iBAAiB,CAAC,WAAW,EAAE,cAAc,CAAC,EAAE,CAAC;QACnD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,OAAO;QACL,GAAG,OAAO;QACV,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS;KACvE,CAAC;AACJ,CAAC"}

package/dist/src/execution/step-context.d.ts

@@ -1,27 +0,0 @@
-import type { Channel, DeliverPayload, SessionAuthContext } from "../channel/types.js";
-import type { AshContext } from "../context/container.js";
-import type { HarnessSession, StepInput, StepResult } from "../harness/types.js";
-export interface StepDeliveryInput {
-    readonly auth?: SessionAuthContext | null;
-    readonly payload: DeliverPayload;
-}
-export interface PreparedStepContext {
-    readonly channel: Channel;
-    readonly channelStateSnapshot: Record<string, unknown>;
-    readonly ctx: AshContext;
-    readonly input: StepInput | undefined;
-}
-export declare function prepareStepContext(input: {
-    readonly delivery?: StepDeliveryInput;
-    readonly serializedRuntimeContext: Record<string, unknown>;
-    readonly session: HarnessSession;
-}): Promise<PreparedStepContext>;
-/**
- * Runs one step inside the provider lifecycle and asserts that the
- * channel's serialized state was not mutated during execution.
- *
- * Combines {@link runStep} with a post-step channel stability check so
- * callers do not need to repeat the three-call sequence themselves.
- */
-export declare function runStepWithChannelGuard(prepared: PreparedStepContext, session: HarnessSession, callback: (session: HarnessSession) => Promise<StepResult>): Promise<StepResult>;
-//# sourceMappingURL=step-context.d.ts.map

package/dist/src/execution/step-context.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"step-context.d.ts","sourceRoot":"","sources":["../../../src/execution/step-context.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACvF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAM1D,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEjF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;CAClC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvD,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAAC;CACvC;AAED,wBAAsB,kBAAkB,CAAC,KAAK,EAAE;IAC9C,QAAQ,CAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IACtC,QAAQ,CAAC,wBAAwB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3D,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;CAClC,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA0B/B;AAED;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,mBAAmB,EAC7B,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,UAAU,CAAC,GACzD,OAAO,CAAC,UAAU,CAAC,CAQrB"}

package/dist/src/execution/step-context.js

@@ -1,54 +0,0 @@
-import { isDeepStrictEqual } from "node:util";
-import { hydrateDurableContext } from "../context/durable-context.js";
-import { AuthKey, ChannelKey } from "../context/keys.js";
-import { runStep } from "../context/run-step.js";
-import { deserializeRuntimeContext } from "../context/serialize.js";
-import { seedPendingInputRequestsContext } from "../harness/input-requests.js";
-export async function prepareStepContext(input) {
-    const ctx = await deserializeRuntimeContext(input.serializedRuntimeContext);
-    await hydrateDurableContext(ctx, input.session);
-    seedPendingInputRequestsContext(ctx, input.session);
-    if (input.delivery?.auth !== undefined) {
-        ctx.set(AuthKey, input.delivery.auth ?? null);
-    }
-    const channel = ctx.get(ChannelKey);
-    const channelStateSnapshot = channel.serialize();
-    const resolved = input.delivery !== undefined ? await channel.onDeliver(ctx, input.delivery.payload) : undefined;
-    assertChannelStateIsStable({
-        channel,
-        phase: "onDeliver",
-        serializedState: channelStateSnapshot,
-    });
-    return {
-        channel,
-        channelStateSnapshot,
-        ctx,
-        input: resolved,
-    };
-}
-/**
- * Runs one step inside the provider lifecycle and asserts that the
- * channel's serialized state was not mutated during execution.
- *
- * Combines {@link runStep} with a post-step channel stability check so
- * callers do not need to repeat the three-call sequence themselves.
- */
-export async function runStepWithChannelGuard(prepared, session, callback) {
-    const stepResult = await runStep(prepared.ctx, session, callback);
-    assertChannelStateIsStable({
-        channel: prepared.channel,
-        phase: "step execution",
-        serializedState: prepared.channelStateSnapshot,
-    });
-    return stepResult;
-}
-function assertChannelStateIsStable(input) {
-    const currentState = input.channel.serialize();
-    if (isDeepStrictEqual(currentState, input.serializedState)) {
-        return;
-    }
-    throw new Error(`Channel "${input.channel.kind}" mutated its serialized state during ${input.phase}. ` +
-        "Channel constructor state must stay immutable after the run starts. " +
-        "Move per-session mutable data into durable context or session.internal instead.");
-}
-//# sourceMappingURL=step-context.js.map

package/dist/src/execution/step-context.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"step-context.js","sourceRoot":"","sources":["../../../src/execution/step-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAI9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,+BAA+B,EAAE,MAAM,8BAA8B,CAAC;AAe/E,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,KAIxC;IACC,MAAM,GAAG,GAAG,MAAM,yBAAyB,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAC;IAC5E,MAAM,qBAAqB,CAAC,GAAG,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IAChD,+BAA+B,CAAC,GAAG,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IAEpD,IAAI,KAAK,CAAC,QAAQ,EAAE,IAAI,KAAK,SAAS,EAAE,CAAC;QACvC,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,QAAQ,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC;IAChD,CAAC;IAED,MAAM,OAAO,GAAG,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACpC,MAAM,oBAAoB,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IACjD,MAAM,QAAQ,GACZ,KAAK,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,OAAO,CAAC,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAElG,0BAA0B,CAAC;QACzB,OAAO;QACP,KAAK,EAAE,WAAW;QAClB,eAAe,EAAE,oBAAoB;KACtC,CAAC,CAAC;IAEH,OAAO;QACL,OAAO;QACP,oBAAoB;QACpB,GAAG;QACH,KAAK,EAAE,QAAQ;KAChB,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,QAA6B,EAC7B,OAAuB,EACvB,QAA0D;IAE1D,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IAClE,0BAA0B,CAAC;QACzB,OAAO,EAAE,QAAQ,CAAC,OAAO;QACzB,KAAK,EAAE,gBAAgB;QACvB,eAAe,EAAE,QAAQ,CAAC,oBAAoB;KAC/C,CAAC,CAAC;IACH,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,SAAS,0BAA0B,CAAC,KAInC;IACC,MAAM,YAAY,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;IAC/C,IAAI,iBAAiB,CAAC,YAAY,EAAE,KAAK,CAAC,eAAe,CAAC,EAAE,CAAC;QAC3D,OAAO;IACT,CAAC;IAED,MAAM,IAAI,KAAK,CACb,YAAY,KAAK,CAAC,OAAO,CAAC,IAAI,yCAAyC,KAAK,CAAC,KAAK,IAAI;QACpF,sEAAsE;QACtE,iFAAiF,CACpF,CAAC;AACJ,CAAC"}

package/docs/public/migration-guide.md

@@ -1,71 +0,0 @@
-# Migration Guide
-
-Ash now has one durable authored-context model.
-
-## Breaking Changes
-
-- `getState(key)` is now `getContext(key)`.
-- `setState(key, value)` is now `setContext(key, value)`.
-- `ensureContext(key, valueOrFactory)` replaces `ContextKey({ initial })`.
-- `ContextKeyOptions.initial` was removed.
-- Public `ContextKey` values are session-durable by default.
-- `HarnessSession.state` is now split into `session.context` and internal `session.internal`.
-- Tool compaction hooks no longer return `sessionPatch`. Mutate durable context through `ctx` instead.
-
-## Before
-
-```ts
-import { ContextKey, getState, setState } from "experimental-ash";
-
-const NotesKey = new ContextKey("myapp.notes", {
-  initial: () => ({ notes: [] }),
-});
-
-setState(NotesKey, (current) => ({
-  notes: [...current.notes, "hello"],
-}));
-
-return getState(NotesKey);
-```
-
-## After
-
-```ts
-import { ContextKey, ensureContext, getContext, setContext } from "experimental-ash";
-
-const NotesKey = new ContextKey("myapp.notes");
-
-const current = ensureContext(NotesKey, () => ({ notes: [] }));
-
-setContext(NotesKey, {
-  notes: [...current.notes, "hello"],
-});
-
-return getContext(NotesKey);
-```
-
-## Channel Guidance
-
-- Use `channel.onDeliver(ctx, payload)` to seed or extend durable context on every turn.
-- Treat serialized channel state as immutable after the run starts.
-- Move mutable per-session data into durable context or `session.internal`, not onto the channel instance.
-
-## Compaction Hooks
-
-Before:
-
-```ts
-onCompact() {
-  return {
-    sessionPatch: { state: {} },
-  };
-}
-```
-
-After:
-
-```ts
-onCompact({ ctx }) {
-  ctx.set(NotesKey, { notes: [] });
-}
-```