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

package/dist/src/context/container.js

@@ -1,39 +1,63 @@
 import { AsyncLocalStorage } from "node:async_hooks";
+import { resolveKey } from "./key.js";
 /**
  * Default mutable implementation of {@link AshContext}.
  */
-export class AshContextImpl {
-    _store = new Map();
+export class ContextContainer {
+    _durableValues = new Map();
+    _virtualValues = new Map();
     get(key) {
-        const entry = this._store.get(key.name);
-        if (entry === undefined) {
-            throw new Error(`Context key "${key.name}" is not set.`);
+        if (this._virtualValues.has(key.name)) {
+            return this._virtualValues.get(key.name);
         }
-        return entry.value;
+        return this._durableValues.get(key.name);
     }
-    tryGet(key) {
-        return this._store.get(key.name)?.value;
+    require(key) {
+        if (!this.has(key)) {
+            throw new Error(`Context key "${key.name}" is not set.`);
+        }
+        return this.get(key);
     }
     has(key) {
-        return this._store.has(key.name);
+        return this._virtualValues.has(key.name) || this._durableValues.has(key.name);
     }
-    set(key, valueOrFactory) {
-        const value = typeof valueOrFactory === "function"
-            ? valueOrFactory(this.tryGet(key))
-            : valueOrFactory;
-        this._store.set(key.name, { key: key, value });
+    set(key, valueOrUpdater) {
+        const value = typeof valueOrUpdater === "function"
+            ? valueOrUpdater(this.get(key))
+            : valueOrUpdater;
+        this._durableValues.set(key.name, value);
         return value;
     }
-    ensure(key, factory) {
-        const entry = this._store.get(key.name);
-        if (entry !== undefined) {
-            return entry.value;
+    ensure(key, create) {
+        if (this.has(key)) {
+            return this.require(key);
         }
-        return this.set(key, factory());
+        return this.set(key, create());
+    }
+    /**
+     * Clears all step-local provider values from the context.
+     *
+     * The runtime calls this before rebuilding context providers for a new
+     * step.
+     */
+    clearVirtualContext() {
+        this._virtualValues.clear();
+    }
+    /**
+     * Stores a step-local provider value for one key.
+     *
+     * Virtual values shadow durable values for the lifetime of the current
+     * step and are excluded from serialization.
+     */
+    setVirtualContext(key, value) {
+        this._virtualValues.set(key.name, value);
     }
     *entries() {
-        for (const { key, value } of this._store.values()) {
-            yield [key, value];
+        for (const [name, value] of this._durableValues) {
+            const key = resolveKey(name);
+            if (key !== undefined) {
+                yield [key, value];
+            }
         }
     }
 }
@@ -41,7 +65,7 @@ export const contextStorage = new AsyncLocalStorage();
 /**
  * Returns the active context, throwing when called outside a managed scope.
  */
-export function requireContext() {
+export function loadContext() {
     const ctx = contextStorage.getStore();
     if (ctx === undefined) {
         throw new Error("No active Ash context. " +
@@ -49,4 +73,12 @@ export function requireContext() {
     }
     return ctx;
 }
+/**
+ * Narrows a {@link ContextContainer} to the {@link ContextAccessor}
+ * interface. Used by runtime entry points to pass the context to channel
+ * `onDeliver` callbacks without exposing implementation details.
+ */
+export function toContextAccessor(ctx) {
+    return ctx;
+}
 //# sourceMappingURL=container.js.map

package/dist/src/context/container.js.map

@@ -1 +1 @@
-{"version":3,"file":"container.js","sourceRoot":"","sources":["../../../src/context/container.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAoBrD;;GAEG;AACH,MAAM,OAAO,cAAc;IACR,MAAM,GAAG,IAAI,GAAG,EAA6D,CAAC;IAE/F,GAAG,CAAI,GAAuB;QAC5B,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,gBAAgB,GAAG,CAAC,IAAI,eAAe,CAAC,CAAC;QAC3D,CAAC;QACD,OAAO,KAAK,CAAC,KAAU,CAAC;IAC1B,CAAC;IAED,MAAM,CAAI,GAAuB;QAC/B,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,KAAsB,CAAC;IAC3D,CAAC;IAED,GAAG,CAAI,GAAuB;QAC5B,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;IAED,GAAG,CAAI,GAAuB,EAAE,cAA6C;QAC3E,MAAM,KAAK,GACT,OAAO,cAAc,KAAK,UAAU;YAClC,CAAC,CAAE,cAA0C,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC/D,CAAC,CAAC,cAAc,CAAC;QACrB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,GAA+B,EAAE,KAAK,EAAE,CAAC,CAAC;QAC3E,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,CAAI,GAAuB,EAAE,OAAgB;QACjD,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,KAAK,CAAC,KAAU,CAAC;QAC1B,CAAC;QACD,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;IAClC,CAAC;IAED,CAAC,OAAO;QACN,KAAK,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;YAClD,MAAM,CAAC,GAAG,EAAE,KAAK,CAAU,CAAC;QAC9B,CAAC;IACH,CAAC;CACF;AAED,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,iBAAiB,EAAc,CAAC;AAElE;;GAEG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,GAAG,GAAG,cAAc,CAAC,QAAQ,EAAE,CAAC;IACtC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACb,yBAAyB;YACvB,+FAA+F,CAClG,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}
+{"version":3,"file":"container.js","sourceRoot":"","sources":["../../../src/context/container.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,OAAO,EAAyC,UAAU,EAAE,MAAM,UAAU,CAAC;AAoB7E;;GAEG;AACH,MAAM,OAAO,gBAAgB;IACV,cAAc,GAAG,IAAI,GAAG,EAAmB,CAAC;IAC5C,cAAc,GAAG,IAAI,GAAG,EAAmB,CAAC;IAE7D,GAAG,CAAI,GAAkB;QACvB,IAAI,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACtC,OAAO,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAM,CAAC;QAChD,CAAC;QACD,OAAO,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAkB,CAAC;IAC5D,CAAC;IAED,OAAO,CAAI,GAAkB;QAC3B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CAAC,gBAAgB,GAAG,CAAC,IAAI,eAAe,CAAC,CAAC;QAC3D,CAAC;QACD,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAM,CAAC;IAC5B,CAAC;IAED,GAAG,CAAI,GAAkB;QACvB,OAAO,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChF,CAAC;IAED,GAAG,CAAI,GAAkB,EAAE,cAAmD;QAC5E,MAAM,KAAK,GACT,OAAO,cAAc,KAAK,UAAU;YAClC,CAAC,CAAE,cAAgD,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAClE,CAAC,CAAC,cAAc,CAAC;QACrB,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACzC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,CAAI,GAAkB,EAAE,MAAe;QAC3C,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAClB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC;QACD,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC;IACjC,CAAC;IAED;;;;;OAKG;IACH,mBAAmB;QACjB,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,CAAC;IAC9B,CAAC;IAED;;;;;OAKG;IACH,iBAAiB,CAAI,GAAkB,EAAE,KAAQ;QAC/C,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC3C,CAAC;IAED,CAAC,OAAO;QACN,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YAChD,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;YAC7B,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;gBACtB,MAAM,CAAC,GAAG,EAAE,KAAK,CAAU,CAAC;YAC9B,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAED,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,iBAAiB,EAAc,CAAC;AAElE;;GAEG;AACH,MAAM,UAAU,WAAW;IACzB,MAAM,GAAG,GAAG,cAAc,CAAC,QAAQ,EAAE,CAAC;IACtC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACb,yBAAyB;YACvB,+FAA+F,CAClG,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAqB;IACrD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/src/context/key.d.ts

@@ -1,60 +1,89 @@
-export interface ContextDecodeContext {
-    get<T>(key: ContextStoreKey<T>): T;
-    tryGet<T>(key: ContextStoreKey<T>): T | undefined;
+/**
+ * Read-only view over the active context.
+ *
+ * Used by context providers and codec deserialization to read values
+ * without mutating durable context.
+ */
+export interface ContextReader {
+    get<T>(key: ContextKey<T>): T | undefined;
+    require<T>(key: ContextKey<T>): T;
+    has<T>(key: ContextKey<T>): boolean;
+}
+/**
+ * Read/write view over the active context.
+ *
+ * Extends {@link ContextReader} with durable write operations. This is
+ * the narrow contract shared by {@link AshContext} and the channel-facing
+ * `ContextAccessor`.
+ */
+export interface ContextAccessor extends ContextReader {
+    set<T>(key: ContextKey<T>, updater: T | ((current: T | undefined) => T)): T;
+    ensure<T>(key: ContextKey<T>, create: () => T): T;
 }
 /**
  * Serialization hooks for one context key.
  *
- * `deserialize` receives the already-hydrated context so codecs can depend on
- * earlier runtime values such as the compiled runtime bundle.
+ * `deserialize` receives the already-hydrated durable context so codecs can
+ * depend on earlier durable keys such as the compiled runtime bundle.
  */
 export interface ContextKeyCodec<T> {
     serialize(value: T): unknown;
-    deserialize(data: unknown, ctx: ContextDecodeContext): T | Promise<T>;
+    deserialize(data: unknown, ctx: ContextReader): T | Promise<T>;
 }
 export interface ContextKeyOptions<T> {
     readonly codec?: ContextKeyCodec<T>;
 }
-interface RuntimeContextKeyOptions<T> extends ContextKeyOptions<T> {
-    readonly serializable?: boolean;
-}
 /**
- * Public durable context key.
+ * Typed key that identifies a named context slot.
+ *
+ * `ContextKey` is the single authored lookup identity for Ash context.
+ * Durable values are written explicitly through `set()` / `ensure()`.
+ * Virtual values may also be derived each step by a `ContextProvider` and
+ * read through the same key.
+ *
+ * When a key stores a durable value that is not already JSON-safe, declare a
+ * `codec` so the runtime can serialize and deserialize that durable value at
+ * step boundaries.
+ *
+ * @example Declare a durable context key and use it from a tool
+ * ```ts
+ * import { ContextKey, getContext, setContext } from "experimental-ash/context";
+ * import { defineTool } from "experimental-ash/tools";
+ * import { z } from "zod";
+ *
+ * interface NoteListContext {
+ *   readonly notes: readonly string[];
+ * }
+ *
+ * const NoteListKey = new ContextKey<NoteListContext>("notes");
  *
- * Values stored under a `ContextKey` are session-durable. The runtime
- * hydrates them from `session.context` before each step and commits them back
- * after the step completes.
+ * export default defineTool({
+ *   description: "Append a note, or read the running list.",
+ *   inputSchema: z.object({ note: z.string().optional() }),
+ *   async execute({ note }) {
+ *     if (note) {
+ *       setContext(NoteListKey, (current) => ({
+ *         notes: [...(current?.notes ?? []), note],
+ *       }));
+ *     }
+ *
+ *     return getContext(NoteListKey);
+ *   },
+ * });
+ * ```
+ *
+ * Every key self-registers in a global registry so the serialization layer
+ * can resolve string names back to typed keys without an explicit list.
+ * Construct each key exactly once at module scope; constructing the same
+ * key name twice is a programmer error.
  */
 export declare class ContextKey<T> {
-    readonly codec?: ContextKeyCodec<T>;
     readonly name: string;
-    constructor(name: string, options?: ContextKeyOptions<T>);
-}
-/**
- * Private runtime-only key used for seed values, providers, and other
- * framework internals that must not be persisted on `session.context`.
- */
-export declare class RuntimeContextKey<T> {
     readonly codec?: ContextKeyCodec<T>;
-    readonly name: string;
-    readonly serializable: boolean;
-    constructor(name: string, options?: RuntimeContextKeyOptions<T>);
+    constructor(name: string, options?: ContextKeyOptions<T>);
 }
-export type ContextStoreKey<T> = ContextKey<T> | RuntimeContextKey<T>;
-export declare function isDurableContextKey(key: ContextStoreKey<unknown>): key is ContextKey<unknown>;
-export declare function isRuntimeContextKey(key: ContextStoreKey<unknown>): key is RuntimeContextKey<unknown>;
-/**
- * Looks up one registered durable key by name.
- */
-export declare function resolveContextKey(name: string): ContextKey<unknown> | undefined;
-/**
- * Looks up one registered runtime key by name.
- */
-export declare function resolveRuntimeContextKey(name: string): RuntimeContextKey<unknown> | undefined;
 /**
- * Returns all registered runtime keys that participate in runtime-seed
- * serialization across durable workflow boundaries.
+ * Looks up a registered key by name. Returns `undefined` for unknown names.
  */
-export declare function getSerializableRuntimeContextKeys(): Iterable<RuntimeContextKey<unknown>>;
-export {};
+export declare function resolveKey(name: string): ContextKey<unknown> | undefined;
 //# sourceMappingURL=key.d.ts.map

package/dist/src/context/key.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"key.d.ts","sourceRoot":"","sources":["../../../src/context/key.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,oBAAoB;IACnC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACnC,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;CACnD;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,SAAS,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC;IAC7B,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,oBAAoB,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACvE;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC;CACrC;AAED,UAAU,wBAAwB,CAAC,CAAC,CAAE,SAAQ,iBAAiB,CAAC,CAAC,CAAC;IAChE,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CACjC;AAUD;;;;;;GAMG;AACH,qBAAa,UAAU,CAAC,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAiB,CAAC,CAAC,CAAM;CAM7D;AAED;;;GAGG;AACH,qBAAa,iBAAiB,CAAC,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;gBAEnB,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,wBAAwB,CAAC,CAAC,CAAM;CAWpE;AAED,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAC;AAEtE,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,eAAe,CAAC,OAAO,CAAC,GAAG,GAAG,IAAI,UAAU,CAAC,OAAO,CAAC,CAE7F;AAED,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,eAAe,CAAC,OAAO,CAAC,GAC5B,GAAG,IAAI,iBAAiB,CAAC,OAAO,CAAC,CAEnC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,SAAS,CAE/E;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAAC,OAAO,CAAC,GAAG,SAAS,CAE7F;AAED;;;GAGG;AACH,wBAAgB,iCAAiC,IAAI,QAAQ,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAExF"}
+{"version":3,"file":"key.d.ts","sourceRoot":"","sources":["../../../src/context/key.ts"],"names":[],"mappings":"AAOA;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;IAC1C,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAClC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;CACrC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAgB,SAAQ,aAAa;IACpD,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC;IAC5E,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;CACnD;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,SAAS,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC;IAC7B,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,aAAa,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAChE;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,qBAAa,UAAU,CAAC,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC;gBAExB,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAiB,CAAC,CAAC,CAAM;CAK7D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,SAAS,CAExE"}

package/dist/src/context/key.js

@@ -1,79 +1,66 @@
 /**
- * Global registries mapping key names to instances.
- *
- * Durable context keys are public/authored keys persisted on `session.context`.
- * Runtime context keys are private framework keys used for seed values,
- * providers, and runtime-only bookkeeping inside one step.
+ * Global registry mapping key names to instances. Populated automatically
+ * by the {@link ContextKey} constructor so `deserializeContext` can resolve
+ * string names back to typed keys without an explicit list.
  */
-const durableKeyRegistry = new Map();
-const runtimeKeyRegistry = new Map();
-const serializableRuntimeKeyRegistry = new Map();
-const registeredKeyNames = new Set();
-function registerKeyName(name) {
-    if (registeredKeyNames.has(name)) {
-        throw new Error(`Context key "${name}" was registered more than once.`);
-    }
-    registeredKeyNames.add(name);
-}
+const keyRegistry = new Map();
 /**
- * Public durable context key.
+ * Typed key that identifies a named context slot.
+ *
+ * `ContextKey` is the single authored lookup identity for Ash context.
+ * Durable values are written explicitly through `set()` / `ensure()`.
+ * Virtual values may also be derived each step by a `ContextProvider` and
+ * read through the same key.
+ *
+ * When a key stores a durable value that is not already JSON-safe, declare a
+ * `codec` so the runtime can serialize and deserialize that durable value at
+ * step boundaries.
+ *
+ * @example Declare a durable context key and use it from a tool
+ * ```ts
+ * import { ContextKey, getContext, setContext } from "experimental-ash/context";
+ * import { defineTool } from "experimental-ash/tools";
+ * import { z } from "zod";
+ *
+ * interface NoteListContext {
+ *   readonly notes: readonly string[];
+ * }
  *
- * Values stored under a `ContextKey` are session-durable. The runtime
- * hydrates them from `session.context` before each step and commits them back
- * after the step completes.
+ * const NoteListKey = new ContextKey<NoteListContext>("notes");
+ *
+ * export default defineTool({
+ *   description: "Append a note, or read the running list.",
+ *   inputSchema: z.object({ note: z.string().optional() }),
+ *   async execute({ note }) {
+ *     if (note) {
+ *       setContext(NoteListKey, (current) => ({
+ *         notes: [...(current?.notes ?? []), note],
+ *       }));
+ *     }
+ *
+ *     return getContext(NoteListKey);
+ *   },
+ * });
+ * ```
+ *
+ * Every key self-registers in a global registry so the serialization layer
+ * can resolve string names back to typed keys without an explicit list.
+ * Construct each key exactly once at module scope; constructing the same
+ * key name twice is a programmer error.
  */
 export class ContextKey {
-    codec;
     name;
-    constructor(name, options = {}) {
-        registerKeyName(name);
-        this.name = name;
-        this.codec = options.codec;
-        durableKeyRegistry.set(name, this);
-    }
-}
-/**
- * Private runtime-only key used for seed values, providers, and other
- * framework internals that must not be persisted on `session.context`.
- */
-export class RuntimeContextKey {
     codec;
-    name;
-    serializable;
     constructor(name, options = {}) {
-        registerKeyName(name);
         this.name = name;
         this.codec = options.codec;
-        this.serializable = options.serializable ?? false;
-        runtimeKeyRegistry.set(name, this);
-        if (this.serializable) {
-            serializableRuntimeKeyRegistry.set(name, this);
-        }
+        keyRegistry.set(name, this);
     }
 }
-export function isDurableContextKey(key) {
-    return key instanceof ContextKey;
-}
-export function isRuntimeContextKey(key) {
-    return key instanceof RuntimeContextKey;
-}
-/**
- * Looks up one registered durable key by name.
- */
-export function resolveContextKey(name) {
-    return durableKeyRegistry.get(name);
-}
-/**
- * Looks up one registered runtime key by name.
- */
-export function resolveRuntimeContextKey(name) {
-    return runtimeKeyRegistry.get(name);
-}
 /**
- * Returns all registered runtime keys that participate in runtime-seed
- * serialization across durable workflow boundaries.
+ * Looks up a registered key by name. Returns `undefined` for unknown names.
  */
-export function getSerializableRuntimeContextKeys() {
-    return serializableRuntimeKeyRegistry.values();
+export function resolveKey(name) {
+    return keyRegistry.get(name);
 }
 //# sourceMappingURL=key.js.map

package/dist/src/context/key.js.map

@@ -1 +1 @@
-{"version":3,"file":"key.js","sourceRoot":"","sources":["../../../src/context/key.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,kBAAkB,GAAG,IAAI,GAAG,EAA+B,CAAC;AAClE,MAAM,kBAAkB,GAAG,IAAI,GAAG,EAAsC,CAAC;AACzE,MAAM,8BAA8B,GAAG,IAAI,GAAG,EAAsC,CAAC;AACrF,MAAM,kBAAkB,GAAG,IAAI,GAAG,EAAU,CAAC;AA0B7C,SAAS,eAAe,CAAC,IAAY;IACnC,IAAI,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,gBAAgB,IAAI,kCAAkC,CAAC,CAAC;IAC1E,CAAC;IAED,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,OAAO,UAAU;IACZ,KAAK,CAAsB;IAC3B,IAAI,CAAS;IAEtB,YAAY,IAAY,EAAE,UAAgC,EAAE;QAC1D,eAAe,CAAC,IAAI,CAAC,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC3B,kBAAkB,CAAC,GAAG,CAAC,IAAI,EAAE,IAA2B,CAAC,CAAC;IAC5D,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,iBAAiB;IACnB,KAAK,CAAsB;IAC3B,IAAI,CAAS;IACb,YAAY,CAAU;IAE/B,YAAY,IAAY,EAAE,UAAuC,EAAE;QACjE,eAAe,CAAC,IAAI,CAAC,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,KAAK,CAAC;QAClD,kBAAkB,CAAC,GAAG,CAAC,IAAI,EAAE,IAAkC,CAAC,CAAC;QAEjE,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,8BAA8B,CAAC,GAAG,CAAC,IAAI,EAAE,IAAkC,CAAC,CAAC;QAC/E,CAAC;IACH,CAAC;CACF;AAID,MAAM,UAAU,mBAAmB,CAAC,GAA6B;IAC/D,OAAO,GAAG,YAAY,UAAU,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,GAA6B;IAE7B,OAAO,GAAG,YAAY,iBAAiB,CAAC;AAC1C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACtC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,wBAAwB,CAAC,IAAY;IACnD,OAAO,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACtC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iCAAiC;IAC/C,OAAO,8BAA8B,CAAC,MAAM,EAAE,CAAC;AACjD,CAAC"}
+{"version":3,"file":"key.js","sourceRoot":"","sources":["../../../src/context/key.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,GAAG,IAAI,GAAG,EAA+B,CAAC;AAyC3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,OAAO,UAAU;IACZ,IAAI,CAAS;IACb,KAAK,CAAsB;IAEpC,YAAY,IAAY,EAAE,UAAgC,EAAE;QAC1D,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC3B,WAAW,CAAC,GAAG,CAAC,IAAI,EAAE,IAA2B,CAAC,CAAC;IACrD,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC"}

package/dist/src/context/keys.d.ts

@@ -2,7 +2,7 @@ import { type Channel, type SessionAuthContext, type SessionParent, type Session
 import type { SandboxAccess } from "../execution/sandboxes/types.js";
 import type { SkillAccess } from "../execution/skills/types.js";
 import { getCompiledRuntimeAgentBundle } from "../runtime/sessions/compiled-agent-cache.js";
-import { RuntimeContextKey } from "./key.js";
+import { ContextKey } from "./key.js";
 export type { SessionAuthContext, SessionParent, SessionTurn } from "../channel/types.js";
 export { AuthKey, ContinuationTokenKey, InitiatorAuthKey, ModeKey, ParentSessionKey, SessionIdKey, } from "./seed-keys.js";
 /**
@@ -25,14 +25,14 @@ export interface Session {
     readonly sessionId: string;
     readonly turn: SessionTurn;
 }
-export declare const ChannelKey: RuntimeContextKey<Channel>;
+export declare const ChannelKey: ContextKey<Channel>;
 /**
  * Bundle returned by the compiled-agent cache. Carries the resolved agent
  * graph, registries, and the active node's turn agent.
  */
 export type CompiledBundle = Awaited<ReturnType<typeof getCompiledRuntimeAgentBundle>>;
-export declare const BundleKey: RuntimeContextKey<import("../runtime/sessions/compiled-agent-cache.js").CompiledRuntimeAgentBundle>;
-export declare const SessionKey: RuntimeContextKey<Session>;
-export declare const SandboxKey: RuntimeContextKey<SandboxAccess>;
-export declare const SkillKey: RuntimeContextKey<SkillAccess>;
+export declare const BundleKey: ContextKey<import("../runtime/sessions/compiled-agent-cache.js").CompiledRuntimeAgentBundle>;
+export declare const SessionKey: ContextKey<Session>;
+export declare const SandboxKey: ContextKey<SandboxAccess>;
+export declare const SkillKey: ContextKey<SkillAccess>;
 //# sourceMappingURL=keys.d.ts.map

package/dist/src/context/keys.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../../src/context/keys.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EAGZ,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,WAAW,EACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAGhE,OAAO,EAAE,6BAA6B,EAAE,MAAM,6CAA6C,CAAC;AAC5F,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAG7C,YAAY,EAAE,kBAAkB,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAE1F,OAAO,EACL,OAAO,EACP,oBAAoB,EACpB,gBAAgB,EAChB,OAAO,EACP,gBAAgB,EAChB,YAAY,GACb,MAAM,gBAAgB,CAAC;AAMxB;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC5C,QAAQ,CAAC,SAAS,EAAE,kBAAkB,GAAG,IAAI,CAAC;CAC/C;AAED;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;CAC5B;AAWD,eAAO,MAAM,UAAU,4BAqBrB,CAAC;AAEH;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,6BAA6B,CAAC,CAAC,CAAC;AAOvF,eAAO,MAAM,SAAS,qGAepB,CAAC;AAMH,eAAO,MAAM,UAAU,4BAAgD,CAAC;AACxE,eAAO,MAAM,UAAU,kCAAsD,CAAC;AAC9E,eAAO,MAAM,QAAQ,gCAAkD,CAAC"}
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../../src/context/keys.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EAGZ,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,WAAW,EACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAGhE,OAAO,EAAE,6BAA6B,EAAE,MAAM,6CAA6C,CAAC;AAC5F,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAGtC,YAAY,EAAE,kBAAkB,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAE1F,OAAO,EACL,OAAO,EACP,oBAAoB,EACpB,gBAAgB,EAChB,OAAO,EACP,gBAAgB,EAChB,YAAY,GACb,MAAM,gBAAgB,CAAC;AAMxB;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC5C,QAAQ,CAAC,SAAS,EAAE,kBAAkB,GAAG,IAAI,CAAC;CAC/C;AAED;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;CAC5B;AAWD,eAAO,MAAM,UAAU,qBAoBrB,CAAC;AAEH;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,6BAA6B,CAAC,CAAC,CAAC;AAOvF,eAAO,MAAM,SAAS,8FAcpB,CAAC;AAMH,eAAO,MAAM,UAAU,qBAAyC,CAAC;AACjE,eAAO,MAAM,UAAU,2BAA+C,CAAC;AACvE,eAAO,MAAM,QAAQ,yBAA2C,CAAC"}

package/dist/src/context/keys.js

@@ -1,10 +1,10 @@
 import { getChannelClassKind, } from "../channel/types.js";
 import { deserializeRuntimeChannel } from "../runtime/channels/registry.js";
 import { getCompiledRuntimeAgentBundle } from "../runtime/sessions/compiled-agent-cache.js";
-import { RuntimeContextKey } from "./key.js";
+import { ContextKey } from "./key.js";
 // Re-export seed keys so existing consumers of `context/keys` keep working.
 export { AuthKey, ContinuationTokenKey, InitiatorAuthKey, ModeKey, ParentSessionKey, SessionIdKey, } from "./seed-keys.js";
-export const ChannelKey = new RuntimeContextKey("ash.channel", {
+export const ChannelKey = new ContextKey("ash.channel", {
     codec: {
         serialize(channel) {
             return {
@@ -13,16 +13,15 @@ export const ChannelKey = new RuntimeContextKey("ash.channel", {
             };
         },
         deserialize(data, ctx) {
-            const bundle = ctx.tryGet(BundleKey);
+            const bundle = ctx.get(BundleKey);
             if (bundle === undefined) {
                 throw new Error('Cannot deserialize "ash.channel" before "ash.bundle". The runtime bundle must be present in context.');
             }
             return deserializeRuntimeChannel(bundle.channelRegistry, data);
         },
     },
-    serializable: true,
 });
-export const BundleKey = new RuntimeContextKey("ash.bundle", {
+export const BundleKey = new ContextKey("ash.bundle", {
     codec: {
         serialize: (bundle) => ({
             nodeSelector: bundle.nodeSelector,
@@ -36,12 +35,11 @@ export const BundleKey = new RuntimeContextKey("ash.bundle", {
             });
         },
     },
-    serializable: true,
 });
 // ---------------------------------------------------------------------------
 // Derived keys — reconstructed by providers each step, never serialized
 // ---------------------------------------------------------------------------
-export const SessionKey = new RuntimeContextKey("ash.session");
-export const SandboxKey = new RuntimeContextKey("ash.sandbox");
-export const SkillKey = new RuntimeContextKey("ash.skill");
+export const SessionKey = new ContextKey("ash.session");
+export const SandboxKey = new ContextKey("ash.sandbox");
+export const SkillKey = new ContextKey("ash.skill");
 //# sourceMappingURL=keys.js.map

package/dist/src/context/keys.js.map

@@ -1 +1 @@
-{"version":3,"file":"keys.js","sourceRoot":"","sources":["../../../src/context/keys.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,mBAAmB,GAIpB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,yBAAyB,EAAE,MAAM,iCAAiC,CAAC;AAE5E,OAAO,EAAE,6BAA6B,EAAE,MAAM,6CAA6C,CAAC;AAC5F,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAI7C,4EAA4E;AAC5E,OAAO,EACL,OAAO,EACP,oBAAoB,EACpB,gBAAgB,EAChB,OAAO,EACP,gBAAgB,EAChB,YAAY,GACb,MAAM,gBAAgB,CAAC;AAqCxB,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,iBAAiB,CAAU,aAAa,EAAE;IACtE,KAAK,EAAE;QACL,SAAS,CAAC,OAAO;YACf,OAAO;gBACL,IAAI,EAAE,mBAAmB,CAAC,OAAO,CAAC,WAA2B,CAAC;gBAC9D,KAAK,EAAE,OAAO,CAAC,SAAS,EAAE;aAC3B,CAAC;QACJ,CAAC;QACD,WAAW,CAAC,IAAI,EAAE,GAAG;YACnB,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YAErC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,MAAM,IAAI,KAAK,CACb,sGAAsG,CACvG,CAAC;YACJ,CAAC;YAED,OAAO,yBAAyB,CAAC,MAAM,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC;QACjE,CAAC;KACF;IACD,YAAY,EAAE,IAAI;CACnB,CAAC,CAAC;AAaH,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,iBAAiB,CAAiB,YAAY,EAAE;IAC3E,KAAK,EAAE;QACL,SAAS,EAAE,CAAC,MAAM,EAAoB,EAAE,CAAC,CAAC;YACxC,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,MAAM,EAAE,MAAM,CAAC,uBAAuB;SACvC,CAAC;QACF,WAAW,EAAE,CAAC,IAAI,EAAE,EAAE;YACpB,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,IAAwB,CAAC;YAC1D,OAAO,6BAA6B,CAAC;gBACnC,uBAAuB,EAAE,MAAM;gBAC/B,YAAY;aACb,CAAC,CAAC;QACL,CAAC;KACF;IACD,YAAY,EAAE,IAAI;CACnB,CAAC,CAAC;AAEH,8EAA8E;AAC9E,wEAAwE;AACxE,8EAA8E;AAE9E,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,iBAAiB,CAAU,aAAa,CAAC,CAAC;AACxE,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,iBAAiB,CAAgB,aAAa,CAAC,CAAC;AAC9E,MAAM,CAAC,MAAM,QAAQ,GAAG,IAAI,iBAAiB,CAAc,WAAW,CAAC,CAAC"}
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../../../src/context/keys.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,mBAAmB,GAIpB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,yBAAyB,EAAE,MAAM,iCAAiC,CAAC;AAE5E,OAAO,EAAE,6BAA6B,EAAE,MAAM,6CAA6C,CAAC;AAC5F,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAItC,4EAA4E;AAC5E,OAAO,EACL,OAAO,EACP,oBAAoB,EACpB,gBAAgB,EAChB,OAAO,EACP,gBAAgB,EAChB,YAAY,GACb,MAAM,gBAAgB,CAAC;AAqCxB,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,UAAU,CAAU,aAAa,EAAE;IAC/D,KAAK,EAAE;QACL,SAAS,CAAC,OAAO;YACf,OAAO;gBACL,IAAI,EAAE,mBAAmB,CAAC,OAAO,CAAC,WAA2B,CAAC;gBAC9D,KAAK,EAAE,OAAO,CAAC,SAAS,EAAE;aAC3B,CAAC;QACJ,CAAC;QACD,WAAW,CAAC,IAAI,EAAE,GAAG;YACnB,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAElC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,MAAM,IAAI,KAAK,CACb,sGAAsG,CACvG,CAAC;YACJ,CAAC;YAED,OAAO,yBAAyB,CAAC,MAAM,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC;QACjE,CAAC;KACF;CACF,CAAC,CAAC;AAaH,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,UAAU,CAAiB,YAAY,EAAE;IACpE,KAAK,EAAE;QACL,SAAS,EAAE,CAAC,MAAM,EAAoB,EAAE,CAAC,CAAC;YACxC,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,MAAM,EAAE,MAAM,CAAC,uBAAuB;SACvC,CAAC;QACF,WAAW,EAAE,CAAC,IAAI,EAAE,EAAE;YACpB,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,IAAwB,CAAC;YAC1D,OAAO,6BAA6B,CAAC;gBACnC,uBAAuB,EAAE,MAAM;gBAC/B,YAAY;aACb,CAAC,CAAC;QACL,CAAC;KACF;CACF,CAAC,CAAC;AAEH,8EAA8E;AAC9E,wEAAwE;AACxE,8EAA8E;AAE9E,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,UAAU,CAAU,aAAa,CAAC,CAAC;AACjE,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,UAAU,CAAgB,aAAa,CAAC,CAAC;AACvE,MAAM,CAAC,MAAM,QAAQ,GAAG,IAAI,UAAU,CAAc,WAAW,CAAC,CAAC"}

package/dist/src/context/node.d.ts

@@ -1,8 +1,8 @@
-import type { AshContext } from "./container.js";
+import type { ContextReader } from "./provider.js";
 /**
  * Returns the active runtime node from the compiled bundle on the
  * context. The bundle is already resolved to the correct node (root or
  * subagent) at run start.
  */
-export declare function getActiveRuntimeNode(ctx: AshContext): import("../runtime/graph.js").ResolvedRuntimeAgentNode;
+export declare function getActiveRuntimeNode(ctx: ContextReader): import("../runtime/graph.js").ResolvedRuntimeAgentNode;
 //# sourceMappingURL=node.d.ts.map

package/dist/src/context/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../../src/context/node.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAGjD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,UAAU,0DAEnD"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../../src/context/node.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,aAAa,0DAEtD"}

package/dist/src/context/node.js

@@ -5,6 +5,6 @@ import { BundleKey } from "./keys.js";
  * subagent) at run start.
  */
 export function getActiveRuntimeNode(ctx) {
-    return ctx.get(BundleKey).graph.root;
+    return ctx.require(BundleKey).graph.root;
 }
 //# sourceMappingURL=node.js.map

package/dist/src/context/node.js.map

@@ -1 +1 @@
-{"version":3,"file":"node.js","sourceRoot":"","sources":["../../../src/context/node.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAe;IAClD,OAAO,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC;AACvC,CAAC"}
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../../../src/context/node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAGtC;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAkB;IACrD,OAAO,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC;AAC3C,CAAC"}

package/dist/src/context/provider.d.ts

@@ -1,24 +1,37 @@
 import type { HarnessSession } from "../harness/types.js";
-import type { AshContext } from "./container.js";
-import type { ContextStoreKey } from "./key.js";
+import type { ContextKey, ContextReader } from "./key.js";
+export type { ContextReader } from "./key.js";
 /**
- * Value returned by a provider's `create` method.
+ * Public derive-only provider that rebuilds one virtual value each step.
  *
- * `value` is the live instance stored on the context.  `session` is an
- * optionally modified harness session (e.g. with enriched instructions).
+ * Provider output is available through `require(key)` for the current
+ * step and is never serialized.
+ */
+export interface ContextProvider<T> {
+    readonly key: ContextKey<T>;
+    create(ctx: ContextReader): T | undefined | Promise<T | undefined>;
+}
+/**
+ * Value returned by a framework provider's `create` method.
+ *
+ * `value` is the live step-local instance stored on the context. `session`
+ * carries an optional harness session patch produced while deriving that
+ * value.
  */
 export interface ProviderResult<T> {
     readonly value: T;
     readonly session?: HarnessSession;
 }
 /**
- * Provider that creates a derived value from seed keys and the harness
- * session.  Providers that mutate state during a step implement `commit`
- * to persist changes back onto the harness session.
+ * Framework-only provider contract.
+ *
+ * Framework providers may derive virtual values from context, observe the
+ * current harness session, and optionally commit mutable provider-owned state
+ * back onto the harness session after the authored step completes.
  */
-export interface ContextProvider<T> {
-    readonly key: ContextStoreKey<T>;
-    create(ctx: AshContext, session: HarnessSession): ProviderResult<T> | undefined | Promise<ProviderResult<T> | undefined>;
+export interface FrameworkContextProvider<T> {
+    readonly key: ContextKey<T>;
+    create(ctx: ContextReader, session: HarnessSession): ProviderResult<T> | undefined | Promise<ProviderResult<T> | undefined>;
     commit?(value: T, session: HarnessSession): HarnessSession | Promise<HarnessSession>;
 }
 //# sourceMappingURL=provider.d.ts.map

package/dist/src/context/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../src/context/provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC;IAEjC,MAAM,CACJ,GAAG,EAAE,UAAU,EACf,OAAO,EAAE,cAAc,GACtB,cAAc,CAAC,CAAC,CAAC,GAAG,SAAS,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAE1E,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CACtF"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../src/context/provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE1D,YAAY,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;IAE5B,MAAM,CAAC,GAAG,EAAE,aAAa,GAAG,CAAC,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;CACpE;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;CACnC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,wBAAwB,CAAC,CAAC;IACzC,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;IAE5B,MAAM,CACJ,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE,cAAc,GACtB,cAAc,CAAC,CAAC,CAAC,GAAG,SAAS,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAE1E,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CACtF"}

package/dist/src/context/providers/connection.d.ts

@@ -1,4 +1,4 @@
 import type { ConnectionRegistry } from "../../runtime/connections/types.js";
-import type { ContextProvider } from "../provider.js";
-export declare const connectionProvider: ContextProvider<ConnectionRegistry>;
+import type { FrameworkContextProvider } from "../provider.js";
+export declare const connectionProvider: FrameworkContextProvider<ConnectionRegistry>;
 //# sourceMappingURL=connection.d.ts.map

package/dist/src/context/providers/connection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../../../src/context/providers/connection.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAI7E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtD,eAAO,MAAM,kBAAkB,EAAE,eAAe,CAAC,kBAAkB,CAYlE,CAAC"}
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../../../src/context/providers/connection.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAI7E,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAE/D,eAAO,MAAM,kBAAkB,EAAE,wBAAwB,CAAC,kBAAkB,CAY3E,CAAC"}

package/dist/src/context/providers/connection.js

@@ -5,7 +5,7 @@ import { getActiveRuntimeNode } from "../node.js";
 export const connectionProvider = {
     key: ConnectionRegistryKey,
     create(ctx, _session) {
-        const bundle = ctx.tryGet(BundleKey);
+        const bundle = ctx.get(BundleKey);
         if (bundle === undefined)
             return undefined;
         const node = getActiveRuntimeNode(ctx);

package/dist/src/context/providers/connection.js.map

@@ -1 +1 @@
-{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../../../src/context/providers/connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC;AAE/E,OAAO,EAAE,qBAAqB,EAAE,MAAM,oDAAoD,CAAC;AAC3F,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAGlD,MAAM,CAAC,MAAM,kBAAkB,GAAwC;IACrE,GAAG,EAAE,qBAAqB;IAE1B,MAAM,CAAC,GAAG,EAAE,QAAQ;QAClB,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACrC,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAC3C,MAAM,IAAI,GAAG,oBAAoB,CAAC,GAAG,CAAC,CAAC;QACvC,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,EAAE,WAAW,CAAC;QAC5C,IAAI,CAAC,WAAW,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QAE/D,OAAO,EAAE,KAAK,EAAE,IAAI,sBAAsB,CAAC,WAAW,CAAC,EAAE,CAAC;IAC5D,CAAC;CACF,CAAC"}
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../../../src/context/providers/connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC;AAE/E,OAAO,EAAE,qBAAqB,EAAE,MAAM,oDAAoD,CAAC;AAC3F,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAGlD,MAAM,CAAC,MAAM,kBAAkB,GAAiD;IAC9E,GAAG,EAAE,qBAAqB;IAE1B,MAAM,CAAC,GAAG,EAAE,QAAQ;QAClB,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAClC,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAC3C,MAAM,IAAI,GAAG,oBAAoB,CAAC,GAAG,CAAC,CAAC;QACvC,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,EAAE,WAAW,CAAC;QAC5C,IAAI,CAAC,WAAW,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QAE/D,OAAO,EAAE,KAAK,EAAE,IAAI,sBAAsB,CAAC,WAAW,CAAC,EAAE,CAAC;IAC5D,CAAC;CACF,CAAC"}

package/dist/src/context/providers/sandbox.d.ts

@@ -1,4 +1,4 @@
 import type { SandboxAccess } from "../../execution/sandboxes/types.js";
-import type { ContextProvider } from "../provider.js";
-export declare const sandboxProvider: ContextProvider<SandboxAccess>;
+import type { FrameworkContextProvider } from "../provider.js";
+export declare const sandboxProvider: FrameworkContextProvider<SandboxAccess>;
 //# sourceMappingURL=sandbox.d.ts.map