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

package/dist/src/compiler/normalize-connection.js

@@ -0,0 +1,29 @@
+import { normalizeMcpClientConnectionDefinition } from "../internal/authored-definition/connection.js";
+import { loadModuleBackedDefinition } from "./normalize-helpers.js";
+/**
+ * Compiles one authored connection module into the serializable metadata
+ * stored on the compiled agent manifest.
+ *
+ * The compiled manifest holds only serializable data. The live
+ * `authorization` callback is resolved at runtime by re-importing the
+ * authored module -- see `runtime/resolve-connection.ts`. Compile-time
+ * still imports and validates the module so authoring errors surface
+ * during `ash build`.
+ */
+export async function compileConnectionDefinition(agentRoot, source) {
+    const normalized = normalizeMcpClientConnectionDefinition(await loadModuleBackedDefinition({
+        agentRoot,
+        kind: "connection",
+        source,
+    }), `Expected the connection export "${source.exportName ?? "default"}" from "${source.logicalPath}" to match the public Ash shape.`);
+    return {
+        connectionName: source.connectionName,
+        description: normalized.description,
+        exportName: source.exportName,
+        logicalPath: source.logicalPath,
+        sourceId: source.sourceId,
+        sourceKind: "module",
+        url: normalized.url,
+    };
+}
+//# sourceMappingURL=normalize-connection.js.map

package/dist/src/compiler/normalize-connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-connection.js","sourceRoot":"","sources":["../../../src/compiler/normalize-connection.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sCAAsC,EAAE,MAAM,+CAA+C,CAAC;AAEvG,OAAO,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AAEpE;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,SAAiB,EACjB,MAA2B;IAE3B,MAAM,UAAU,GAAG,sCAAsC,CACvD,MAAM,0BAA0B,CAAC;QAC/B,SAAS;QACT,IAAI,EAAE,YAAY;QAClB,MAAM;KACP,CAAC,EACF,mCAAmC,MAAM,CAAC,UAAU,IAAI,SAAS,WAAW,MAAM,CAAC,WAAW,kCAAkC,CACjI,CAAC;IAEF,OAAO;QACL,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,WAAW,EAAE,UAAU,CAAC,WAAW;QACnC,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,UAAU,EAAE,QAAQ;QACpB,GAAG,EAAE,UAAU,CAAC,GAAG;KACpB,CAAC;AACJ,CAAC"}

package/dist/src/compiler/normalize-manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"normalize-manifest.d.ts","sourceRoot":"","sources":["../../../src/compiler/normalize-manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,EACL,KAAK,qBAAqB,EAM3B,MAAM,eAAe,CAAC;AAYvB;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,mBAAmB,GAC5B,OAAO,CAAC,qBAAqB,CAAC,CAoBhC"}
+{"version":3,"file":"normalize-manifest.d.ts","sourceRoot":"","sources":["../../../src/compiler/normalize-manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,EACL,KAAK,qBAAqB,EAM3B,MAAM,eAAe,CAAC;AAavB;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,mBAAmB,GAC5B,OAAO,CAAC,qBAAqB,CAAC,CAoBhC"}

package/dist/src/compiler/normalize-manifest.js

@@ -2,6 +2,7 @@ import { createCompiledAgentManifest, createCompiledAgentNodeManifest, ROOT_COMP
 import { createCompiledRuntimeModelCatalogLoader } from "./model-catalog.js";
 import { compileAgentConfig } from "./normalize-agent-config.js";
 import { compileChannelDefinition } from "./normalize-channel.js";
+import { compileConnectionDefinition } from "./normalize-connection.js";
 import { compilePromptLayer } from "./normalize-prompt-layer.js";
 import { compileSandboxDefinition } from "./normalize-sandbox.js";
 import { compileScheduleDefinition } from "./normalize-schedule.js";
@@ -48,6 +49,7 @@ async function compileAgentNodeManifest(manifest, context, configOverride) {
         appRoot: manifest.appRoot,
         channels: await Promise.all(manifest.channels.map((channelSource) => compileChannelDefinition(manifest.agentRoot, channelSource))),
         config: await compileAgentConfig(manifest, context, configOverride),
+        connections: await Promise.all(manifest.connections.map((connectionSource) => compileConnectionDefinition(manifest.agentRoot, connectionSource))),
         diagnosticsSummary: manifest.diagnosticsSummary,
         disabledFrameworkTools,
         promptLayers: await Promise.all(manifest.promptLayers.map((promptLayer) => compilePromptLayer(manifest.agentRoot, promptLayer))),

package/dist/src/compiler/normalize-manifest.js.map

@@ -1 +1 @@
-{"version":3,"file":"normalize-manifest.js","sourceRoot":"","sources":["../../../src/compiler/normalize-manifest.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"normalize-manifest.js","sourceRoot":"","sources":["../../../src/compiler/normalize-manifest.ts"],"names":[],"mappings":"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"}

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

@@ -17,28 +17,29 @@ export declare function getSession(): Session;
  */
 export declare function getSandbox<Name extends SandboxName>(name: Name): Promise<AshRuntimeSandboxMap[Name]>;
 /**
- * Returns the current value of a state key in the active context.
- *
- * State keys are durable — they survive workflow step boundaries and
- * compaction. Declare a state key with the `initial` option on
- * {@link ContextKey} to opt in.
+ * Returns the current durable context value for one key in the active scope.
  *
  * @throws When called outside of a managed step execution.
  */
-export declare function getState<T>(key: ContextKey<T>): T;
+export declare function getContext<T>(key: ContextKey<T>): T;
 /**
- * Sets the value of a state key in the active context.
+ * Sets one durable context value in the active scope.
  *
  * Accepts either a direct value or an updater function that receives the
- * current state and returns the next state (like React's `setState`).
+ * current value and returns the next value.
+ *
+ * @throws When called outside of a managed step execution.
+ */
+export declare function setContext<T>(key: ContextKey<T>, valueOrFactory: T | ((v: T | undefined) => T)): T;
+/**
+ * Returns the current durable context value for one key, creating it when the
+ * key is absent.
  *
- * The new value is persisted back to the session at the end of the step.
- * Always return a new object from the updater rather than mutating the
- * existing one so change detection (reference inequality) works correctly.
+ * The provided default may be a direct value or a lazy factory.
  *
  * @throws When called outside of a managed step execution.
  */
-export declare function setState<T>(key: ContextKey<T>, valueOrUpdater: T | ((current: T) => T)): void;
+export declare function ensureContext<T>(key: ContextKey<T>, factory: () => T): T;
 /**
  * Returns a handle for the named skill visible to the current agent.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"accessors.d.ts","sourceRoot":"","sources":["../../../src/context/accessors.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,KAAK,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAE1F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EAAc,KAAK,OAAO,EAAwB,MAAM,WAAW,CAAC;AAG3E,YAAY,EACV,OAAO,EACP,WAAW,EACX,kBAAkB,EAClB,aAAa,EACb,WAAW,GACZ,MAAM,WAAW,CAAC;AAEnB;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,OAAO,CAEpC;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,IAAI,SAAS,WAAW,EACvD,IAAI,EAAE,IAAI,GACT,OAAO,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAsBrC;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAEjD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,CAO7F;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,WAAW,CAuBxD"}
+{"version":3,"file":"accessors.d.ts","sourceRoot":"","sources":["../../../src/context/accessors.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,KAAK,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAE1F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EAAc,KAAK,OAAO,EAAwB,MAAM,WAAW,CAAC;AAG3E,YAAY,EACV,OAAO,EACP,WAAW,EACX,kBAAkB,EAClB,aAAa,EACb,WAAW,GACZ,MAAM,WAAW,CAAC;AAEnB;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,OAAO,CAEpC;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,IAAI,SAAS,WAAW,EACvD,IAAI,EAAE,IAAI,GACT,OAAO,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAsBrC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAEnD;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC1B,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,EAClB,cAAc,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,CAAC,GAC5C,CAAC,CAEH;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,CAExE;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,WAAW,CAuBxD"}

package/dist/src/context/accessors.js

@@ -31,35 +31,34 @@ export async function getSandbox(name) {
     return sandbox;
 }
 /**
- * Returns the current value of a state key in the active context.
- *
- * State keys are durable — they survive workflow step boundaries and
- * compaction. Declare a state key with the `initial` option on
- * {@link ContextKey} to opt in.
+ * Returns the current durable context value for one key in the active scope.
  *
  * @throws When called outside of a managed step execution.
  */
-export function getState(key) {
+export function getContext(key) {
     return requireContext().get(key);
 }
 /**
- * Sets the value of a state key in the active context.
+ * Sets one durable context value in the active scope.
  *
  * Accepts either a direct value or an updater function that receives the
- * current state and returns the next state (like React's `setState`).
+ * current value and returns the next value.
+ *
+ * @throws When called outside of a managed step execution.
+ */
+export function setContext(key, valueOrFactory) {
+    return requireContext().set(key, valueOrFactory);
+}
+/**
+ * Returns the current durable context value for one key, creating it when the
+ * key is absent.
  *
- * The new value is persisted back to the session at the end of the step.
- * Always return a new object from the updater rather than mutating the
- * existing one so change detection (reference inequality) works correctly.
+ * The provided default may be a direct value or a lazy factory.
  *
  * @throws When called outside of a managed step execution.
  */
-export function setState(key, valueOrUpdater) {
-    const ctx = requireContext();
-    const next = typeof valueOrUpdater === "function"
-        ? valueOrUpdater(ctx.get(key))
-        : valueOrUpdater;
-    ctx.set(key, next);
+export function ensureContext(key, factory) {
+    return requireContext().ensure(key, factory);
 }
 /**
  * Returns a handle for the named skill visible to the current agent.

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

@@ -1 +1 @@
-{"version":3,"file":"accessors.js","sourceRoot":"","sources":["../../../src/context/accessors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"accessors.js","sourceRoot":"","sources":["../../../src/context/accessors.ts"],"names":[],"mappings":"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"}

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

@@ -1,33 +1,31 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-import type { ContextKey } from "./key.js";
+import type { ContextStoreKey } from "./key.js";
 /**
  * Keyed value container that backs one Ash execution scope.
  *
- * Seed values are set by the runtime entry point; derived values are
- * populated by providers during {@link runStep}.
+ * Runtime seed values are set by the execution layer, durable context values
+ * are hydrated from `session.context`, and provider-created runtime values are
+ * populated during `runStep`.
  */
 export interface AshContext {
-    get<T>(key: ContextKey<T>): T;
-    tryGet<T>(key: ContextKey<T>): T | undefined;
-    has<T>(key: ContextKey<T>): boolean;
-    set<T>(key: ContextKey<T>, value: T): void;
-    /**
-     * Iterates all key/value pairs currently stored in the context.
-     * Used by the serialization layer to persist context at step boundaries.
-     */
-    entries(): Iterable<readonly [ContextKey<unknown>, unknown]>;
+    get<T>(key: ContextStoreKey<T>): T;
+    tryGet<T>(key: ContextStoreKey<T>): T | undefined;
+    has<T>(key: ContextStoreKey<T>): boolean;
+    set<T>(key: ContextStoreKey<T>, valueOrFactory: T | ((v: T | undefined) => T)): T;
+    ensure<T>(key: ContextStoreKey<T>, factory: () => T): T;
+    entries(): Iterable<readonly [ContextStoreKey<unknown>, unknown]>;
 }
 /**
  * Default mutable implementation of {@link AshContext}.
  */
 export declare class AshContextImpl implements AshContext {
-    private readonly _keys;
-    private readonly _values;
-    get<T>(key: ContextKey<T>): T;
-    tryGet<T>(key: ContextKey<T>): T | undefined;
-    has<T>(key: ContextKey<T>): boolean;
-    set<T>(key: ContextKey<T>, value: T): void;
-    entries(): Generator<readonly [ContextKey<unknown>, unknown]>;
+    private readonly _store;
+    get<T>(key: ContextStoreKey<T>): T;
+    tryGet<T>(key: ContextStoreKey<T>): T | undefined;
+    has<T>(key: ContextStoreKey<T>): boolean;
+    set<T>(key: ContextStoreKey<T>, valueOrFactory: T | ((v: T | undefined) => T)): T;
+    ensure<T>(key: ContextStoreKey<T>, factory: () => T): T;
+    entries(): Generator<readonly [ContextStoreKey<unknown>, unknown]>;
 }
 export declare const contextStorage: AsyncLocalStorage<AshContext>;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../../../src/context/container.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC9B,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;IAC7C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;IACpC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IAE3C;;;OAGG;IACH,OAAO,IAAI,QAAQ,CAAC,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;CAC9D;AAED;;GAEG;AACH,qBAAa,cAAe,YAAW,UAAU;IAC/C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0C;IAChE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8B;IAEtD,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC;IAO7B,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS;IAI5C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO;IAInC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAKzC,OAAO,IAAI,SAAS,CAAC,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;CAQ/D;AAED,eAAO,MAAM,cAAc,+BAAsC,CAAC;AAElE;;GAEG;AACH,wBAAgB,cAAc,IAAI,UAAU,CAS3C"}
+{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../../../src/context/container.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,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;IAClD,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;IACzC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC;IAClF,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IACxD,OAAO,IAAI,QAAQ,CAAC,SAAS,CAAC,eAAe,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;CACnE;AAED;;GAEG;AACH,qBAAa,cAAe,YAAW,UAAU;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwE;IAE/F,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,CAAC;IAQlC,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS;IAIjD,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,OAAO;IAIxC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,CAAC,GAAG,CAAC;IASjF,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC;IAQtD,OAAO,IAAI,SAAS,CAAC,SAAS,CAAC,eAAe,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;CAKpE;AAED,eAAO,MAAM,cAAc,+BAAsC,CAAC;AAElE;;GAEG;AACH,wBAAgB,cAAc,IAAI,UAAU,CAS3C"}

package/dist/src/context/container.js

@@ -3,30 +3,37 @@ import { AsyncLocalStorage } from "node:async_hooks";
  * Default mutable implementation of {@link AshContext}.
  */
 export class AshContextImpl {
-    _keys = new Map();
-    _values = new Map();
+    _store = new Map();
     get(key) {
-        if (!this._values.has(key.name)) {
+        const entry = this._store.get(key.name);
+        if (entry === undefined) {
             throw new Error(`Context key "${key.name}" is not set.`);
         }
-        return this._values.get(key.name);
+        return entry.value;
     }
     tryGet(key) {
-        return this._values.get(key.name);
+        return this._store.get(key.name)?.value;
     }
     has(key) {
-        return this._values.has(key.name);
+        return this._store.has(key.name);
     }
-    set(key, value) {
-        this._keys.set(key.name, key);
-        this._values.set(key.name, value);
+    set(key, valueOrFactory) {
+        const value = typeof valueOrFactory === "function"
+            ? valueOrFactory(this.tryGet(key))
+            : valueOrFactory;
+        this._store.set(key.name, { key: key, value });
+        return value;
+    }
+    ensure(key, factory) {
+        const entry = this._store.get(key.name);
+        if (entry !== undefined) {
+            return entry.value;
+        }
+        return this.set(key, factory());
     }
     *entries() {
-        for (const [name, value] of this._values) {
-            const key = this._keys.get(name);
-            if (key !== undefined) {
-                yield [key, value];
-            }
+        for (const { key, value } of this._store.values()) {
+            yield [key, value];
         }
     }
 }

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;AAuBrD;;GAEG;AACH,MAAM,OAAO,cAAc;IACR,KAAK,GAAG,IAAI,GAAG,EAA+B,CAAC;IAC/C,OAAO,GAAG,IAAI,GAAG,EAAmB,CAAC;IAEtD,GAAG,CAAI,GAAkB;QACvB,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CAAC,gBAAgB,GAAG,CAAC,IAAI,eAAe,CAAC,CAAC;QAC3D,CAAC;QACD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAM,CAAC;IACzC,CAAC;IAED,MAAM,CAAI,GAAkB;QAC1B,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAkB,CAAC;IACrD,CAAC;IAED,GAAG,CAAI,GAAkB;QACvB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;IAED,GAAG,CAAI,GAAkB,EAAE,KAAQ;QACjC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,GAA0B,CAAC,CAAC;QACrD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACpC,CAAC;IAED,CAAC,OAAO;QACN,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACzC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACjC,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,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;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"}

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

@@ -0,0 +1,18 @@
+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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,49 @@
+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

@@ -0,0 +1 @@
+{"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/context/key.d.ts

@@ -1,100 +1,60 @@
+export interface ContextDecodeContext {
+    get<T>(key: ContextStoreKey<T>): T;
+    tryGet<T>(key: ContextStoreKey<T>): T | undefined;
+}
 /**
- * Options accepted by the {@link ContextKey} constructor.
+ * Serialization hooks for one context key.
  *
- * - `initial` — marks the key as **durable state**. The factory returns the
- *   default value used the first time the state is read on a session, and
- *   the framework persists subsequent writes back across `"use step"`
- *   boundaries. Read and mutate the value with
- *   {@link getState} / {@link setState} from `experimental-ash`.
- * - `codec` — serialization hooks for values that are not JSON-safe (e.g.
- *   live class instances). Most app-authored state is plain JSON and does
- *   not need a codec.
+ * `deserialize` receives the already-hydrated context so codecs can depend on
+ * earlier runtime values such as the compiled runtime bundle.
  */
+export interface ContextKeyCodec<T> {
+    serialize(value: T): unknown;
+    deserialize(data: unknown, ctx: ContextDecodeContext): T | Promise<T>;
+}
 export interface ContextKeyOptions<T> {
-    readonly codec?: {
-        serialize(value: T): unknown;
-        deserialize(data: unknown): T | Promise<T>;
-    };
-    readonly initial?: () => T;
+    readonly codec?: ContextKeyCodec<T>;
+}
+interface RuntimeContextKeyOptions<T> extends ContextKeyOptions<T> {
+    readonly serializable?: boolean;
 }
 /**
- * Typed key that identifies a value inside an {@link AshContext} container.
- *
- * Use a `ContextKey` to declare a piece of durable, per-session state that
- * tools, steps, and model callbacks can read and write inside an Ash
- * execution scope. The key is declared once at module top-level and reused
- * everywhere — the value is stored on the active session, not on the key.
- *
- * @example Declare a durable state key and use it from a tool
- * ```ts
- * import { ContextKey, getState, setState } from "experimental-ash";
- * import { defineTool } from "experimental-ash/tools";
- * import { z } from "zod";
- *
- * interface NoteListState {
- *   readonly notes: readonly string[];
- * }
- *
- * // `initial` makes this a state key — its value survives across
- * // workflow step boundaries and compaction. The name must be unique
- * // across the whole agent process.
- * const NoteListStateKey = new ContextKey<NoteListState>("notes", {
- *   initial: () => ({ 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) {
- *       setState(NoteListStateKey, (current) => ({
- *         notes: [...current.notes, note],
- *       }));
- *     }
- *     return getState(NoteListStateKey);
- *   },
- * });
- * ```
- *
- * Keys with an `initial` factory are **state keys** — durable mutable values
- * hydrated from the session at step start and persisted back at step end.
- * Keys without `initial` are ephemeral and only live for the current step.
+ * Public durable context key.
  *
- * State keys participate in compaction via tool-level `onCompact` hooks
- * declared on a `ToolDefinition`, not on the key itself.
- *
- * Keys that hold values which are not JSON-safe (e.g. live class instances)
- * must declare a `codec` so the framework can serialize/deserialize at step
- * boundaries.
- *
- * 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.
+ * 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 declare class ContextKey<T> {
+    readonly codec?: ContextKeyCodec<T>;
     readonly name: string;
-    readonly codec?: {
-        serialize(value: T): unknown;
-        deserialize(data: unknown): T | Promise<T>;
-    };
-    /**
-     * When provided, this key stores durable state on the harness session
-     * across workflow step boundaries. The factory returns the default value
-     * used when no persisted state exists on the session yet.
-     */
-    readonly initial?: () => T;
     constructor(name: string, options?: ContextKeyOptions<T>);
 }
 /**
- * Looks up a registered key by name. Returns `undefined` for unknown names.
+ * Private runtime-only key used for seed values, providers, and other
+ * framework internals that must not be persisted on `session.context`.
  */
-export declare function resolveKey(name: string): ContextKey<unknown> | undefined;
+export declare class RuntimeContextKey<T> {
+    readonly codec?: ContextKeyCodec<T>;
+    readonly name: string;
+    readonly serializable: boolean;
+    constructor(name: string, options?: RuntimeContextKeyOptions<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>;
 /**
- * Returns all registered state keys (keys with an `initial` factory).
- *
- * Used by `runStep` to generically hydrate and commit durable state without
- * knowledge of specific key identities.
+ * 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.
  */
-export declare function getStateKeys(): Iterable<ContextKey<unknown>>;
+export declare function getSerializableRuntimeContextKeys(): Iterable<RuntimeContextKey<unknown>>;
+export {};
 //# 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":"AAaA;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE;QACf,SAAS,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC;QAC7B,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;KAC5C,CAAC;IACF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,qBAAa,UAAU,CAAC,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE;QACf,SAAS,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC;QAC7B,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;KAC5C,CAAC;IAEF;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC;gBAEf,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAiB,CAAC,CAAC,CAAM;CAS7D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,SAAS,CAExE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,IAAI,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAE5D"}
+{"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"}