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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (144) hide show
  1. package/dist/src/channel/types.d.ts +14 -11
  2. package/dist/src/channel/types.d.ts.map +1 -1
  3. package/dist/src/channel/types.js +6 -0
  4. package/dist/src/channel/types.js.map +1 -1
  5. package/dist/src/context/accessors.d.ts +26 -11
  6. package/dist/src/context/accessors.d.ts.map +1 -1
  7. package/dist/src/context/accessors.js +38 -21
  8. package/dist/src/context/accessors.js.map +1 -1
  9. package/dist/src/context/container.d.ts +37 -16
  10. package/dist/src/context/container.d.ts.map +1 -1
  11. package/dist/src/context/container.js +54 -15
  12. package/dist/src/context/container.js.map +1 -1
  13. package/dist/src/context/key.d.ts +38 -57
  14. package/dist/src/context/key.d.ts.map +1 -1
  15. package/dist/src/context/key.js +17 -52
  16. package/dist/src/context/key.js.map +1 -1
  17. package/dist/src/context/keys.js +1 -1
  18. package/dist/src/context/keys.js.map +1 -1
  19. package/dist/src/context/node.d.ts +2 -2
  20. package/dist/src/context/node.d.ts.map +1 -1
  21. package/dist/src/context/node.js +1 -1
  22. package/dist/src/context/node.js.map +1 -1
  23. package/dist/src/context/provider.d.ts +23 -10
  24. package/dist/src/context/provider.d.ts.map +1 -1
  25. package/dist/src/context/providers/connection.d.ts +2 -2
  26. package/dist/src/context/providers/connection.d.ts.map +1 -1
  27. package/dist/src/context/providers/connection.js +1 -1
  28. package/dist/src/context/providers/connection.js.map +1 -1
  29. package/dist/src/context/providers/sandbox.d.ts +2 -2
  30. package/dist/src/context/providers/sandbox.d.ts.map +1 -1
  31. package/dist/src/context/providers/sandbox.js +2 -2
  32. package/dist/src/context/providers/sandbox.js.map +1 -1
  33. package/dist/src/context/providers/session.d.ts +2 -2
  34. package/dist/src/context/providers/session.d.ts.map +1 -1
  35. package/dist/src/context/providers/session.js +4 -4
  36. package/dist/src/context/providers/session.js.map +1 -1
  37. package/dist/src/context/providers/skill.d.ts +2 -2
  38. package/dist/src/context/providers/skill.d.ts.map +1 -1
  39. package/dist/src/context/providers/skill.js +2 -2
  40. package/dist/src/context/providers/skill.js.map +1 -1
  41. package/dist/src/context/run-step.d.ts +9 -10
  42. package/dist/src/context/run-step.d.ts.map +1 -1
  43. package/dist/src/context/run-step.js +30 -24
  44. package/dist/src/context/run-step.js.map +1 -1
  45. package/dist/src/context/serialize.d.ts +3 -3
  46. package/dist/src/context/serialize.d.ts.map +1 -1
  47. package/dist/src/context/serialize.js +3 -3
  48. package/dist/src/context/serialize.js.map +1 -1
  49. package/dist/src/execution/continuous-entry.d.ts +2 -2
  50. package/dist/src/execution/continuous-entry.d.ts.map +1 -1
  51. package/dist/src/execution/continuous-entry.js +12 -6
  52. package/dist/src/execution/continuous-entry.js.map +1 -1
  53. package/dist/src/execution/node-step.js +1 -0
  54. package/dist/src/execution/node-step.js.map +1 -1
  55. package/dist/src/execution/runtime-context.d.ts +3 -3
  56. package/dist/src/execution/runtime-context.d.ts.map +1 -1
  57. package/dist/src/execution/runtime-context.js +3 -3
  58. package/dist/src/execution/runtime-context.js.map +1 -1
  59. package/dist/src/execution/sandboxes/read-file-tool.js +2 -2
  60. package/dist/src/execution/sandboxes/read-file-tool.js.map +1 -1
  61. package/dist/src/execution/sandboxes/require-sandbox.js +2 -2
  62. package/dist/src/execution/sandboxes/require-sandbox.js.map +1 -1
  63. package/dist/src/execution/sandboxes/write-file-tool.d.ts.map +1 -1
  64. package/dist/src/execution/sandboxes/write-file-tool.js +3 -3
  65. package/dist/src/execution/sandboxes/write-file-tool.js.map +1 -1
  66. package/dist/src/execution/subagent-tool.js +6 -6
  67. package/dist/src/execution/subagent-tool.js.map +1 -1
  68. package/dist/src/execution/tool-compaction.js +2 -2
  69. package/dist/src/execution/tool-compaction.js.map +1 -1
  70. package/dist/src/execution/types.d.ts +1 -0
  71. package/dist/src/execution/types.d.ts.map +1 -1
  72. package/dist/src/execution/workflow-entry.d.ts.map +1 -1
  73. package/dist/src/execution/workflow-entry.js +8 -3
  74. package/dist/src/execution/workflow-entry.js.map +1 -1
  75. package/dist/src/execution/workflow-steps.d.ts.map +1 -1
  76. package/dist/src/execution/workflow-steps.js +25 -8
  77. package/dist/src/execution/workflow-steps.js.map +1 -1
  78. package/dist/src/harness/execute-tool.d.ts +1 -0
  79. package/dist/src/harness/execute-tool.d.ts.map +1 -1
  80. package/dist/src/harness/execute-tool.js.map +1 -1
  81. package/dist/src/harness/input-requests.d.ts +1 -0
  82. package/dist/src/harness/input-requests.d.ts.map +1 -1
  83. package/dist/src/harness/input-requests.js +15 -5
  84. package/dist/src/harness/input-requests.js.map +1 -1
  85. package/dist/src/harness/tool-loop.d.ts.map +1 -1
  86. package/dist/src/harness/tool-loop.js +19 -1
  87. package/dist/src/harness/tool-loop.js.map +1 -1
  88. package/dist/src/harness/tools.js +5 -1
  89. package/dist/src/harness/tools.js.map +1 -1
  90. package/dist/src/internal/application/package.js +1 -1
  91. package/dist/src/internal/authored-definition/connection.d.ts.map +1 -1
  92. package/dist/src/internal/authored-definition/connection.js +14 -1
  93. package/dist/src/internal/authored-definition/connection.js.map +1 -1
  94. package/dist/src/public/definitions/connections/mcp.d.ts +13 -0
  95. package/dist/src/public/definitions/connections/mcp.d.ts.map +1 -1
  96. package/dist/src/public/definitions/connections/mcp.js.map +1 -1
  97. package/dist/src/public/definitions/tool.d.ts +6 -3
  98. package/dist/src/public/definitions/tool.d.ts.map +1 -1
  99. package/dist/src/public/definitions/tool.js.map +1 -1
  100. package/dist/src/public/index.d.ts +2 -1
  101. package/dist/src/public/index.d.ts.map +1 -1
  102. package/dist/src/public/index.js +1 -1
  103. package/dist/src/public/index.js.map +1 -1
  104. package/dist/src/runtime/connections/registry.d.ts +6 -0
  105. package/dist/src/runtime/connections/registry.d.ts.map +1 -1
  106. package/dist/src/runtime/connections/registry.js +8 -0
  107. package/dist/src/runtime/connections/registry.js.map +1 -1
  108. package/dist/src/runtime/connections/types.d.ts +2 -0
  109. package/dist/src/runtime/connections/types.d.ts.map +1 -1
  110. package/dist/src/runtime/framework-tools/connection-execute.d.ts.map +1 -1
  111. package/dist/src/runtime/framework-tools/connection-execute.js +17 -6
  112. package/dist/src/runtime/framework-tools/connection-execute.js.map +1 -1
  113. package/dist/src/runtime/framework-tools/connection-search.js +2 -2
  114. package/dist/src/runtime/framework-tools/connection-search.js.map +1 -1
  115. package/dist/src/runtime/framework-tools/file-state.d.ts +1 -3
  116. package/dist/src/runtime/framework-tools/file-state.d.ts.map +1 -1
  117. package/dist/src/runtime/framework-tools/file-state.js +3 -7
  118. package/dist/src/runtime/framework-tools/file-state.js.map +1 -1
  119. package/dist/src/runtime/framework-tools/skill.d.ts.map +1 -1
  120. package/dist/src/runtime/framework-tools/skill.js +4 -6
  121. package/dist/src/runtime/framework-tools/skill.js.map +1 -1
  122. package/dist/src/runtime/framework-tools/todo.d.ts.map +1 -1
  123. package/dist/src/runtime/framework-tools/todo.js +5 -7
  124. package/dist/src/runtime/framework-tools/todo.js.map +1 -1
  125. package/dist/src/runtime/prompt/connections.d.ts.map +1 -1
  126. package/dist/src/runtime/prompt/connections.js +3 -2
  127. package/dist/src/runtime/prompt/connections.js.map +1 -1
  128. package/dist/src/runtime/resolve-agent-graph.js +3 -2
  129. package/dist/src/runtime/resolve-agent-graph.js.map +1 -1
  130. package/dist/src/runtime/resolve-connection.d.ts.map +1 -1
  131. package/dist/src/runtime/resolve-connection.js +3 -0
  132. package/dist/src/runtime/resolve-connection.js.map +1 -1
  133. package/dist/src/runtime/types.d.ts +13 -0
  134. package/dist/src/runtime/types.d.ts.map +1 -1
  135. package/docs/internals/context.md +65 -39
  136. package/docs/public/channels/README.md +10 -0
  137. package/docs/public/session-context.md +89 -14
  138. package/docs/public/tools.md +19 -20
  139. package/docs/public/typescript-api.md +2 -2
  140. package/package.json +1 -1
  141. package/dist/src/context/state.d.ts +0 -27
  142. package/dist/src/context/state.d.ts.map +0 -1
  143. package/dist/src/context/state.js +0 -53
  144. package/dist/src/context/state.js.map +0 -1
@@ -1,8 +1,10 @@
1
- import type { ContextKey } from "../context/key.js";
1
+ import type { ContextAccessor } from "../context/key.js";
2
+ import type { ContextProvider } from "../context/provider.js";
2
3
  import type { StepInput } from "../harness/types.js";
3
4
  import type { HandleMessageStreamEvent } from "../protocol/message.js";
4
5
  import type { RunMode } from "../run-mode.js";
5
6
  import type { InputResponse } from "../runtime/input/types.js";
7
+ export type { ContextAccessor } from "../context/key.js";
6
8
  /**
7
9
  * Global symbol brand used to recognize Ash channel classes across
8
10
  * independently-loaded copies of the package during compile/runtime tests.
@@ -39,16 +41,6 @@ export interface SessionAuthContext {
39
41
  readonly principalType: string;
40
42
  readonly subject?: string;
41
43
  }
42
- /**
43
- * Narrow accessor passed to {@link Channel.onDeliver} callbacks. Exposes only
44
- * typed get/set with {@link ContextKey} — keeps channel code
45
- * workflow-agnostic and prevents channels from depending on
46
- * {@link AshContext} internals such as `entries()` or `has()`.
47
- */
48
- export interface ContextAccessor {
49
- get<T>(key: ContextKey<T>): T;
50
- set<T>(key: ContextKey<T>, value: T): void;
51
- }
52
44
  /**
53
45
  * Function provided by the runtime that writes one event to the event stream.
54
46
  *
@@ -164,6 +156,13 @@ export interface ChannelClass<C extends Channel = Channel> {
164
156
  * across all serializable channel classes visible to one runtime bundle.
165
157
  */
166
158
  readonly kind: string;
159
+ /**
160
+ * Optional per-step virtual providers attached to this channel class.
161
+ *
162
+ * The runtime rebuilds these providers after `onDeliver()` on every step
163
+ * for sessions using this channel.
164
+ */
165
+ readonly contextProviders?: readonly ContextProvider<unknown>[];
167
166
  /**
168
167
  * Constructs a channel instance. Specific route helpers may constrain the
169
168
  * constructor input shape further (for example Slack channel classes accept
@@ -175,6 +174,10 @@ export interface ChannelClass<C extends Channel = Channel> {
175
174
  * Returns the static durable kind for a channel class.
176
175
  */
177
176
  export declare function getChannelClassKind(channelClass: ChannelClass): string;
177
+ /**
178
+ * Returns the channel-scoped context providers declared on a channel class.
179
+ */
180
+ export declare function getChannelClassContextProviders(channelClass: ChannelClass): readonly ContextProvider<unknown>[];
178
181
  /**
179
182
  * Single input shape consumed by {@link Runtime.run} for both root runs
180
183
  * (started by routes) and delegated child runs (started by the
@@ -1 +1 @@
1
- {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/channel/types.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/channel/types.ts"],"names":[],"mappings":"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"}
@@ -62,4 +62,10 @@ export function getChannelClassKind(channelClass) {
62
62
  }
63
63
  return channelClass.kind;
64
64
  }
65
+ /**
66
+ * Returns the channel-scoped context providers declared on a channel class.
67
+ */
68
+ export function getChannelClassContextProviders(channelClass) {
69
+ return channelClass.contextProviders ?? [];
70
+ }
65
71
  //# sourceMappingURL=types.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/channel/types.ts"],"names":[],"mappings":"AAMA;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;AACnE,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;AAoG3E,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAgB,OAAO;IAC3B;;;;OAIG;IACH,MAAM,CAAU,CAAC,mBAAmB,CAAC,GAAG,IAAI,CAAC;IAC7C;;;;;OAKG;IACH,IAAc,CAAC,uBAAuB,CAAC;QACrC,OAAO,IAAI,CAAC;IACd,CAAC;IACD;;;OAGG;IACgB,cAAc,CAAa;IAE9C;;;OAGG;IACH,IAAI,IAAI;QACN,OAAO,mBAAmB,CAAC,IAAI,CAAC,WAA2B,CAAC,CAAC;IAC/D,CAAC;;AAqDH;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,YAA0B;IAC5D,IAAI,OAAO,YAAY,CAAC,IAAI,KAAK,QAAQ,IAAI,YAAY,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5E,MAAM,IAAI,SAAS,CAAC,+DAA+D,CAAC,CAAC;IACvF,CAAC;IAED,OAAO,YAAY,CAAC,IAAI,CAAC;AAC3B,CAAC"}
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/channel/types.ts"],"names":[],"mappings":"AASA;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;AACnE,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;AAqF3E,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAgB,OAAO;IAC3B;;;;OAIG;IACH,MAAM,CAAU,CAAC,mBAAmB,CAAC,GAAG,IAAI,CAAC;IAC7C;;;;;OAKG;IACH,IAAc,CAAC,uBAAuB,CAAC;QACrC,OAAO,IAAI,CAAC;IACd,CAAC;IACD;;;OAGG;IACgB,cAAc,CAAa;IAE9C;;;OAGG;IACH,IAAI,IAAI;QACN,OAAO,mBAAmB,CAAC,IAAI,CAAC,WAA2B,CAAC,CAAC;IAC/D,CAAC;;AA4DH;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,YAA0B;IAC5D,IAAI,OAAO,YAAY,CAAC,IAAI,KAAK,QAAQ,IAAI,YAAY,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5E,MAAM,IAAI,SAAS,CAAC,+DAA+D,CAAC,CAAC;IACvF,CAAC;IAED,OAAO,YAAY,CAAC,IAAI,CAAC;AAC3B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,+BAA+B,CAC7C,YAA0B;IAE1B,OAAO,YAAY,CAAC,gBAAgB,IAAI,EAAE,CAAC;AAC7C,CAAC"}
@@ -17,28 +17,43 @@ export declare function getSession(): Session;
17
17
  */
18
18
  export declare function getSandbox<Name extends SandboxName>(name: Name): Promise<AshRuntimeSandboxMap[Name]>;
19
19
  /**
20
- * Returns the current value of a state key in the active context.
20
+ * Returns the current value of a context key, or `undefined` when unset.
21
21
  *
22
- * State keys are durable they survive workflow step boundaries and
23
- * compaction. Declare a state key with the `initial` option on
24
- * {@link ContextKey} to opt in.
22
+ * @throws When called outside of a managed step execution.
23
+ */
24
+ export declare function getContext<T>(key: ContextKey<T>): T | undefined;
25
+ /**
26
+ * Returns the current value of a context key, throwing when unset.
27
+ *
28
+ * @throws When the key is not set or when called outside of a managed
29
+ * step execution.
30
+ */
31
+ export declare function requireContext<T>(key: ContextKey<T>): T;
32
+ /**
33
+ * Returns whether the key is currently set in the active context.
25
34
  *
26
35
  * @throws When called outside of a managed step execution.
27
36
  */
28
- export declare function getState<T>(key: ContextKey<T>): T;
37
+ export declare function hasContext<T>(key: ContextKey<T>): boolean;
29
38
  /**
30
- * Sets the value of a state key in the active context.
39
+ * Sets the durable value of a context key in the active context.
31
40
  *
32
41
  * Accepts either a direct value or an updater function that receives the
33
- * current state and returns the next state (like React's `setState`).
42
+ * current value (or `undefined` if unset) and returns the next value.
43
+ *
44
+ * The new durable value is serialized at the end of the step and survives
45
+ * future workflow steps and turns.
34
46
  *
35
- * The new value is persisted back to the session at the end of the step.
36
- * Always return a new object from the updater rather than mutating the
37
- * existing one so change detection (reference inequality) works correctly.
47
+ * @throws When called outside of a managed step execution.
48
+ */
49
+ export declare function setContext<T>(key: ContextKey<T>, valueOrUpdater: T | ((current: T | undefined) => T)): T;
50
+ /**
51
+ * Returns the current value of a context key or initializes and stores a
52
+ * durable value when the key is unset.
38
53
  *
39
54
  * @throws When called outside of a managed step execution.
40
55
  */
41
- export declare function setState<T>(key: ContextKey<T>, valueOrUpdater: T | ((current: T) => T)): void;
56
+ export declare function ensureContext<T>(key: ContextKey<T>, create: () => T): T;
42
57
  /**
43
58
  * Returns a handle for the named skill visible to the current agent.
44
59
  *
@@ -1 +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"}
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;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,CAEzD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC1B,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,EAClB,cAAc,EAAE,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,CAAC,GAClD,CAAC,CAEH;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAEvE;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,WAAW,CAuBxD"}
@@ -1,5 +1,5 @@
1
1
  import { createSkillHandle } from "../execution/skills/handle.js";
2
- import { requireContext } from "./container.js";
2
+ import { loadContext } from "./container.js";
3
3
  import { SandboxKey, SessionKey, SkillKey } from "./keys.js";
4
4
  /**
5
5
  * Returns the active session for the current authored async execution chain.
@@ -7,7 +7,7 @@ import { SandboxKey, SessionKey, SkillKey } from "./keys.js";
7
7
  * @throws When called outside of a managed step execution.
8
8
  */
9
9
  export function getSession() {
10
- return requireContext().get(SessionKey);
10
+ return loadContext().require(SessionKey);
11
11
  }
12
12
  /**
13
13
  * Returns one authored sandbox visible from the current runtime execution.
@@ -16,7 +16,7 @@ export function getSession() {
16
16
  * requested sandbox is not visible.
17
17
  */
18
18
  export async function getSandbox(name) {
19
- const access = requireContext().tryGet(SandboxKey);
19
+ const access = loadContext().get(SandboxKey);
20
20
  if (access === undefined) {
21
21
  throw new Error("Ash sandbox runtime access is unavailable in the current async context. " +
22
22
  "Call getSandbox() only from authored runtime functions such as tools, steps, and model callbacks.");
@@ -31,35 +31,52 @@ export async function getSandbox(name) {
31
31
  return sandbox;
32
32
  }
33
33
  /**
34
- * Returns the current value of a state key in the active context.
34
+ * Returns the current value of a context key, or `undefined` when unset.
35
35
  *
36
- * State keys are durable they survive workflow step boundaries and
37
- * compaction. Declare a state key with the `initial` option on
38
- * {@link ContextKey} to opt in.
36
+ * @throws When called outside of a managed step execution.
37
+ */
38
+ export function getContext(key) {
39
+ return loadContext().get(key);
40
+ }
41
+ /**
42
+ * Returns the current value of a context key, throwing when unset.
43
+ *
44
+ * @throws When the key is not set or when called outside of a managed
45
+ * step execution.
46
+ */
47
+ export function requireContext(key) {
48
+ return loadContext().require(key);
49
+ }
50
+ /**
51
+ * Returns whether the key is currently set in the active context.
39
52
  *
40
53
  * @throws When called outside of a managed step execution.
41
54
  */
42
- export function getState(key) {
43
- return requireContext().get(key);
55
+ export function hasContext(key) {
56
+ return loadContext().has(key);
44
57
  }
45
58
  /**
46
- * Sets the value of a state key in the active context.
59
+ * Sets the durable value of a context key in the active context.
47
60
  *
48
61
  * Accepts either a direct value or an updater function that receives the
49
- * current state and returns the next state (like React's `setState`).
62
+ * current value (or `undefined` if unset) and returns the next value.
63
+ *
64
+ * The new durable value is serialized at the end of the step and survives
65
+ * future workflow steps and turns.
50
66
  *
51
- * The new value is persisted back to the session at the end of the step.
52
- * Always return a new object from the updater rather than mutating the
53
- * existing one so change detection (reference inequality) works correctly.
67
+ * @throws When called outside of a managed step execution.
68
+ */
69
+ export function setContext(key, valueOrUpdater) {
70
+ return loadContext().set(key, valueOrUpdater);
71
+ }
72
+ /**
73
+ * Returns the current value of a context key or initializes and stores a
74
+ * durable value when the key is unset.
54
75
  *
55
76
  * @throws When called outside of a managed step execution.
56
77
  */
57
- export function setState(key, valueOrUpdater) {
58
- const ctx = requireContext();
59
- const next = typeof valueOrUpdater === "function"
60
- ? valueOrUpdater(ctx.get(key))
61
- : valueOrUpdater;
62
- ctx.set(key, next);
78
+ export function ensureContext(key, create) {
79
+ return loadContext().ensure(key, create);
63
80
  }
64
81
  /**
65
82
  * Returns a handle for the named skill visible to the current agent.
@@ -68,7 +85,7 @@ export function setState(key, valueOrUpdater) {
68
85
  * requested skill is not found.
69
86
  */
70
87
  export function getSkill(identifier) {
71
- const access = requireContext().tryGet(SkillKey);
88
+ const access = loadContext().get(SkillKey);
72
89
  if (access === undefined) {
73
90
  throw new Error("Ash skill runtime access is unavailable in the current async context. " +
74
91
  "Call getSkill() only from authored runtime functions such as tools, steps, and model callbacks.");
@@ -1 +1 @@
1
- {"version":3,"file":"accessors.js","sourceRoot":"","sources":["../../../src/context/accessors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAGlE,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,EAAE,UAAU,EAAgB,UAAU,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAW3E;;;;GAIG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO,cAAc,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,IAAU;IAEV,MAAM,MAAM,GAAG,cAAc,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAEnD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACb,0EAA0E;YACxE,mGAAmG,CACtG,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAEvC,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACrB,MAAM,OAAO,GAAG,MAAM,CAAC,gBAAgB,EAAE,CAAC;QAC1C,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzE,MAAM,IAAI,KAAK,CACb,YAAY,IAAI,8DAA8D;YAC5E,sBAAsB,WAAW,GAAG,CACvC,CAAC;IACJ,CAAC;IAED,OAAO,OAAqC,CAAC;AAC/C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ,CAAI,GAAkB;IAC5C,OAAO,cAAc,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACnC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,QAAQ,CAAI,GAAkB,EAAE,cAAuC;IACrF,MAAM,GAAG,GAAG,cAAc,EAAE,CAAC;IAC7B,MAAM,IAAI,GACR,OAAO,cAAc,KAAK,UAAU;QAClC,CAAC,CAAE,cAAoC,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACrD,CAAC,CAAC,cAAc,CAAC;IACrB,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AACrB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,UAAkB;IACzC,MAAM,MAAM,GAAG,cAAc,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAEjD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACb,wEAAwE;YACtE,iGAAiG,CACpG,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACnD,MAAM,MAAM,GAAG,MAAM,CAAC,YAAY,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,UAAU,CAAC,CAAC;IAEtF,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,SAAS,GAAG,MAAM,CAAC,YAAY,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC3D,MAAM,aAAa,GAAG,SAAS,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/E,MAAM,IAAI,KAAK,CACb,UAAU,UAAU,8DAA8D;YAChF,qBAAqB,aAAa,GAAG,CACxC,CAAC;IACJ,CAAC;IAED,OAAO,iBAAiB,CAAC,MAAM,CAAC,CAAC;AACnC,CAAC"}
1
+ {"version":3,"file":"accessors.js","sourceRoot":"","sources":["../../../src/context/accessors.ts"],"names":[],"mappings":"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"}
@@ -1,18 +1,18 @@
1
1
  import { AsyncLocalStorage } from "node:async_hooks";
2
- import type { ContextKey } from "./key.js";
2
+ import { type ContextAccessor, type ContextKey } from "./key.js";
3
3
  /**
4
4
  * Keyed value container that backs one Ash execution scope.
5
5
  *
6
- * Seed values are set by the runtime entry point; derived values are
7
- * populated by providers during {@link runStep}.
6
+ * Durable values are serialized across workflow steps and turns. Virtual
7
+ * values are rebuilt each step by context providers and are never
8
+ * serialized.
9
+ *
10
+ * Extends {@link ContextAccessor} with the `entries()` iterator used by
11
+ * the serialization layer.
8
12
  */
9
- export interface AshContext {
10
- get<T>(key: ContextKey<T>): T;
11
- tryGet<T>(key: ContextKey<T>): T | undefined;
12
- has<T>(key: ContextKey<T>): boolean;
13
- set<T>(key: ContextKey<T>, value: T): void;
13
+ export interface AshContext extends ContextAccessor {
14
14
  /**
15
- * Iterates all key/value pairs currently stored in the context.
15
+ * Iterates all durable key/value pairs currently stored in the context.
16
16
  * Used by the serialization layer to persist context at step boundaries.
17
17
  */
18
18
  entries(): Iterable<readonly [ContextKey<unknown>, unknown]>;
@@ -20,18 +20,39 @@ export interface AshContext {
20
20
  /**
21
21
  * Default mutable implementation of {@link AshContext}.
22
22
  */
23
- export declare class AshContextImpl implements AshContext {
24
- private readonly _keys;
25
- private readonly _values;
26
- get<T>(key: ContextKey<T>): T;
27
- tryGet<T>(key: ContextKey<T>): T | undefined;
23
+ export declare class ContextContainer implements AshContext {
24
+ private readonly _durableValues;
25
+ private readonly _virtualValues;
26
+ get<T>(key: ContextKey<T>): T | undefined;
27
+ require<T>(key: ContextKey<T>): T;
28
28
  has<T>(key: ContextKey<T>): boolean;
29
- set<T>(key: ContextKey<T>, value: T): void;
29
+ set<T>(key: ContextKey<T>, valueOrUpdater: T | ((current: T | undefined) => T)): T;
30
+ ensure<T>(key: ContextKey<T>, create: () => T): T;
31
+ /**
32
+ * Clears all step-local provider values from the context.
33
+ *
34
+ * The runtime calls this before rebuilding context providers for a new
35
+ * step.
36
+ */
37
+ clearVirtualContext(): void;
38
+ /**
39
+ * Stores a step-local provider value for one key.
40
+ *
41
+ * Virtual values shadow durable values for the lifetime of the current
42
+ * step and are excluded from serialization.
43
+ */
44
+ setVirtualContext<T>(key: ContextKey<T>, value: T): void;
30
45
  entries(): Generator<readonly [ContextKey<unknown>, unknown]>;
31
46
  }
32
47
  export declare const contextStorage: AsyncLocalStorage<AshContext>;
33
48
  /**
34
49
  * Returns the active context, throwing when called outside a managed scope.
35
50
  */
36
- export declare function requireContext(): AshContext;
51
+ export declare function loadContext(): AshContext;
52
+ /**
53
+ * Narrows a {@link ContextContainer} to the {@link ContextAccessor}
54
+ * interface. Used by runtime entry points to pass the context to channel
55
+ * `onDeliver` callbacks without exposing implementation details.
56
+ */
57
+ export declare function toContextAccessor(ctx: ContextContainer): ContextAccessor;
37
58
  //# sourceMappingURL=container.d.ts.map
@@ -1 +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"}
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,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAc,MAAM,UAAU,CAAC;AAE7E;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAW,SAAQ,eAAe;IACjD;;;OAGG;IACH,OAAO,IAAI,QAAQ,CAAC,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;CAC9D;AAED;;GAEG;AACH,qBAAa,gBAAiB,YAAW,UAAU;IACjD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA8B;IAC7D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA8B;IAE7D,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS;IAOzC,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC;IAOjC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO;IAInC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,CAAC,GAAG,CAAC;IASlF,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC;IAOjD;;;;;OAKG;IACH,mBAAmB,IAAI,IAAI;IAI3B;;;;;OAKG;IACH,iBAAiB,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAIvD,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,WAAW,IAAI,UAAU,CASxC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,gBAAgB,GAAG,eAAe,CAExE"}
@@ -1,29 +1,60 @@
1
1
  import { AsyncLocalStorage } from "node:async_hooks";
2
+ import { resolveKey } from "./key.js";
2
3
  /**
3
4
  * Default mutable implementation of {@link AshContext}.
4
5
  */
5
- export class AshContextImpl {
6
- _keys = new Map();
7
- _values = new Map();
6
+ export class ContextContainer {
7
+ _durableValues = new Map();
8
+ _virtualValues = new Map();
8
9
  get(key) {
9
- if (!this._values.has(key.name)) {
10
- throw new Error(`Context key "${key.name}" is not set.`);
10
+ if (this._virtualValues.has(key.name)) {
11
+ return this._virtualValues.get(key.name);
11
12
  }
12
- return this._values.get(key.name);
13
+ return this._durableValues.get(key.name);
13
14
  }
14
- tryGet(key) {
15
- return this._values.get(key.name);
15
+ require(key) {
16
+ if (!this.has(key)) {
17
+ throw new Error(`Context key "${key.name}" is not set.`);
18
+ }
19
+ return this.get(key);
16
20
  }
17
21
  has(key) {
18
- return this._values.has(key.name);
22
+ return this._virtualValues.has(key.name) || this._durableValues.has(key.name);
23
+ }
24
+ set(key, valueOrUpdater) {
25
+ const value = typeof valueOrUpdater === "function"
26
+ ? valueOrUpdater(this.get(key))
27
+ : valueOrUpdater;
28
+ this._durableValues.set(key.name, value);
29
+ return value;
30
+ }
31
+ ensure(key, create) {
32
+ if (this.has(key)) {
33
+ return this.require(key);
34
+ }
35
+ return this.set(key, create());
19
36
  }
20
- set(key, value) {
21
- this._keys.set(key.name, key);
22
- this._values.set(key.name, value);
37
+ /**
38
+ * Clears all step-local provider values from the context.
39
+ *
40
+ * The runtime calls this before rebuilding context providers for a new
41
+ * step.
42
+ */
43
+ clearVirtualContext() {
44
+ this._virtualValues.clear();
45
+ }
46
+ /**
47
+ * Stores a step-local provider value for one key.
48
+ *
49
+ * Virtual values shadow durable values for the lifetime of the current
50
+ * step and are excluded from serialization.
51
+ */
52
+ setVirtualContext(key, value) {
53
+ this._virtualValues.set(key.name, value);
23
54
  }
24
55
  *entries() {
25
- for (const [name, value] of this._values) {
26
- const key = this._keys.get(name);
56
+ for (const [name, value] of this._durableValues) {
57
+ const key = resolveKey(name);
27
58
  if (key !== undefined) {
28
59
  yield [key, value];
29
60
  }
@@ -34,7 +65,7 @@ export const contextStorage = new AsyncLocalStorage();
34
65
  /**
35
66
  * Returns the active context, throwing when called outside a managed scope.
36
67
  */
37
- export function requireContext() {
68
+ export function loadContext() {
38
69
  const ctx = contextStorage.getStore();
39
70
  if (ctx === undefined) {
40
71
  throw new Error("No active Ash context. " +
@@ -42,4 +73,12 @@ export function requireContext() {
42
73
  }
43
74
  return ctx;
44
75
  }
76
+ /**
77
+ * Narrows a {@link ContextContainer} to the {@link ContextAccessor}
78
+ * interface. Used by runtime entry points to pass the context to channel
79
+ * `onDeliver` callbacks without exposing implementation details.
80
+ */
81
+ export function toContextAccessor(ctx) {
82
+ return ctx;
83
+ }
45
84
  //# sourceMappingURL=container.js.map
@@ -1 +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"}
1
+ {"version":3,"file":"container.js","sourceRoot":"","sources":["../../../src/context/container.ts"],"names":[],"mappings":"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"}
@@ -1,83 +1,77 @@
1
1
  /**
2
- * Options accepted by the {@link ContextKey} constructor.
2
+ * Read-only view over the active context.
3
3
  *
4
- * - `initial` marks the key as **durable state**. The factory returns the
5
- * default value used the first time the state is read on a session, and
6
- * the framework persists subsequent writes back across `"use step"`
7
- * boundaries. Read and mutate the value with
8
- * {@link getState} / {@link setState} from `experimental-ash`.
9
- * - `codec` — serialization hooks for values that are not JSON-safe (e.g.
10
- * live class instances). Most app-authored state is plain JSON and does
11
- * not need a codec.
4
+ * Used by context providers and codec deserialization to read values
5
+ * without mutating durable context.
12
6
  */
13
- export interface ContextDecodeContext {
14
- get<T>(key: ContextKey<T>): T;
15
- tryGet<T>(key: ContextKey<T>): T | undefined;
7
+ export interface ContextReader {
8
+ get<T>(key: ContextKey<T>): T | undefined;
9
+ require<T>(key: ContextKey<T>): T;
10
+ has<T>(key: ContextKey<T>): boolean;
11
+ }
12
+ /**
13
+ * Read/write view over the active context.
14
+ *
15
+ * Extends {@link ContextReader} with durable write operations. This is
16
+ * the narrow contract shared by {@link AshContext} and the channel-facing
17
+ * `ContextAccessor`.
18
+ */
19
+ export interface ContextAccessor extends ContextReader {
20
+ set<T>(key: ContextKey<T>, updater: T | ((current: T | undefined) => T)): T;
21
+ ensure<T>(key: ContextKey<T>, create: () => T): T;
16
22
  }
17
23
  /**
18
24
  * Serialization hooks for one context key.
19
25
  *
20
- * `deserialize` receives the already-hydrated context so codecs can depend on
21
- * earlier seed values such as the compiled runtime bundle.
26
+ * `deserialize` receives the already-hydrated durable context so codecs can
27
+ * depend on earlier durable keys such as the compiled runtime bundle.
22
28
  */
23
29
  export interface ContextKeyCodec<T> {
24
30
  serialize(value: T): unknown;
25
- deserialize(data: unknown, ctx: ContextDecodeContext): T | Promise<T>;
31
+ deserialize(data: unknown, ctx: ContextReader): T | Promise<T>;
26
32
  }
27
33
  export interface ContextKeyOptions<T> {
28
34
  readonly codec?: ContextKeyCodec<T>;
29
- readonly initial?: () => T;
30
35
  }
31
36
  /**
32
- * Typed key that identifies a value inside an {@link AshContext} container.
37
+ * Typed key that identifies a named context slot.
33
38
  *
34
- * Use a `ContextKey` to declare a piece of durable, per-session state that
35
- * tools, steps, and model callbacks can read and write inside an Ash
36
- * execution scope. The key is declared once at module top-level and reused
37
- * everywhere the value is stored on the active session, not on the key.
39
+ * `ContextKey` is the single authored lookup identity for Ash context.
40
+ * Durable values are written explicitly through `set()` / `ensure()`.
41
+ * Virtual values may also be derived each step by a `ContextProvider` and
42
+ * read through the same key.
38
43
  *
39
- * @example Declare a durable state key and use it from a tool
44
+ * When a key stores a durable value that is not already JSON-safe, declare a
45
+ * `codec` so the runtime can serialize and deserialize that durable value at
46
+ * step boundaries.
47
+ *
48
+ * @example Declare a durable context key and use it from a tool
40
49
  * ```ts
41
- * import { ContextKey, getState, setState } from "experimental-ash";
50
+ * import { ContextKey, getContext, setContext } from "experimental-ash";
42
51
  * import { defineTool } from "experimental-ash/tools";
43
52
  * import { z } from "zod";
44
53
  *
45
- * interface NoteListState {
54
+ * interface NoteListContext {
46
55
  * readonly notes: readonly string[];
47
56
  * }
48
57
  *
49
- * // `initial` makes this a state key — its value survives across
50
- * // workflow step boundaries and compaction. The name must be unique
51
- * // across the whole agent process.
52
- * const NoteListStateKey = new ContextKey<NoteListState>("notes", {
53
- * initial: () => ({ notes: [] }),
54
- * });
58
+ * const NoteListKey = new ContextKey<NoteListContext>("notes");
55
59
  *
56
60
  * export default defineTool({
57
61
  * description: "Append a note, or read the running list.",
58
62
  * inputSchema: z.object({ note: z.string().optional() }),
59
63
  * async execute({ note }) {
60
64
  * if (note) {
61
- * setState(NoteListStateKey, (current) => ({
62
- * notes: [...current.notes, note],
65
+ * setContext(NoteListKey, (current) => ({
66
+ * notes: [...(current?.notes ?? []), note],
63
67
  * }));
64
68
  * }
65
- * return getState(NoteListStateKey);
69
+ *
70
+ * return getContext(NoteListKey);
66
71
  * },
67
72
  * });
68
73
  * ```
69
74
  *
70
- * Keys with an `initial` factory are **state keys** — durable mutable values
71
- * hydrated from the session at step start and persisted back at step end.
72
- * Keys without `initial` are ephemeral and only live for the current step.
73
- *
74
- * State keys participate in compaction via tool-level `onCompact` hooks
75
- * declared on a `ToolDefinition`, not on the key itself.
76
- *
77
- * Keys that hold values which are not JSON-safe (e.g. live class instances)
78
- * must declare a `codec` so the framework can serialize/deserialize at step
79
- * boundaries.
80
- *
81
75
  * Every key self-registers in a global registry so the serialization layer
82
76
  * can resolve string names back to typed keys without an explicit list.
83
77
  * Construct each key exactly once at module scope; constructing the same
@@ -86,23 +80,10 @@ export interface ContextKeyOptions<T> {
86
80
  export declare class ContextKey<T> {
87
81
  readonly name: string;
88
82
  readonly codec?: ContextKeyCodec<T>;
89
- /**
90
- * When provided, this key stores durable state on the harness session
91
- * across workflow step boundaries. The factory returns the default value
92
- * used when no persisted state exists on the session yet.
93
- */
94
- readonly initial?: () => T;
95
83
  constructor(name: string, options?: ContextKeyOptions<T>);
96
84
  }
97
85
  /**
98
86
  * Looks up a registered key by name. Returns `undefined` for unknown names.
99
87
  */
100
88
  export declare function resolveKey(name: string): ContextKey<unknown> | undefined;
101
- /**
102
- * Returns all registered state keys (keys with an `initial` factory).
103
- *
104
- * Used by `runStep` to generically hydrate and commit durable state without
105
- * knowledge of specific key identities.
106
- */
107
- export declare function getStateKeys(): Iterable<ContextKey<unknown>>;
108
89
  //# sourceMappingURL=key.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"key.d.ts","sourceRoot":"","sources":["../../../src/context/key.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,oBAAoB;IACnC,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;CAC9C;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;IACpC,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,eAAe,CAAC,CAAC,CAAC,CAAC;IAEpC;;;;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"}
1
+ {"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"}