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

package/docs/public/tools.md

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

package/docs/public/typescript-api.md

@@ -41,9 +41,11 @@ Most apps use `defineAgent`, `defineTool`, and `defineSandbox` the most.
 ## Runtime Helpers
 
 - `getSession()` - current session, turn, auth, and optional parent lineage
+- `getContext(key)` - read one durable authored context value
+- `setContext(key, value)` - write one durable authored context value
+- `ensureContext(key, valueOrFactory)` - read-or-create one durable context value
 - `getSandbox(name)` - live named sandbox session
 - `getSkill(identifier)` - handle for a named skill visible to the current agent
-- `getState(key)` / `setState(key)` - context-backed runtime state helpers
 
 Related exported types:
 
@@ -61,6 +63,8 @@ sessions must finish inside the current invocation.
 
 These helpers only work inside active authored runtime execution.
 
+Breaking change details and before/after examples live in [`migration-guide.md`](./migration-guide.md).
+
 ## Markdown Helpers
 
 Ash also exports helpers for turning markdown into the same shapes as module-authored definitions:

package/package.json

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

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

@@ -1,27 +0,0 @@
-import type { HarnessSession } from "../harness/types.js";
-import type { AshContext } from "./container.js";
-/**
- * Opaque snapshot returned by {@link hydrateStateKeys} and consumed by
- * {@link commitStateKeys} for reference-equality change detection.
- */
-export type StateSnapshot = ReadonlyMap<string, unknown>;
-/**
- * Hydrates all registered state keys onto the context from `session.state`.
- *
- * For each state key in the global registry:
- * - If `session.state[key.name]` exists, deserializes it (via codec if present).
- * - Otherwise, uses `key.initial()` to produce the default value.
- *
- * Returns an opaque snapshot used by {@link commitStateKeys} to detect which
- * keys were modified during the step.
- */
-export declare function hydrateStateKeys(ctx: AshContext, session: HarnessSession): Promise<StateSnapshot>;
-/**
- * Commits modified state keys back to `session.state`.
- *
- * Compares each state key's current context value against the snapshot taken
- * during hydration. Only keys whose value changed (reference inequality) are
- * written. Returns the session unchanged when nothing was modified.
- */
-export declare function commitStateKeys(ctx: AshContext, session: HarnessSession, snapshot: StateSnapshot): HarnessSession;
-//# sourceMappingURL=state.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/context/state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAGjD;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEzD;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,UAAU,EACf,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,aAAa,CAAC,CAcxB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,UAAU,EACf,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,aAAa,GACtB,cAAc,CAiBhB"}

package/dist/src/context/state.js

@@ -1,53 +0,0 @@
-import { getStateKeys } from "./key.js";
-/**
- * Hydrates all registered state keys onto the context from `session.state`.
- *
- * For each state key in the global registry:
- * - If `session.state[key.name]` exists, deserializes it (via codec if present).
- * - Otherwise, uses `key.initial()` to produce the default value.
- *
- * Returns an opaque snapshot used by {@link commitStateKeys} to detect which
- * keys were modified during the step.
- */
-export async function hydrateStateKeys(ctx, session) {
-    const snapshot = new Map();
-    for (const key of getStateKeys()) {
-        const raw = session.state?.[key.name];
-        let value;
-        if (raw !== undefined) {
-            value = key.codec ? await key.codec.deserialize(raw, ctx) : raw;
-        }
-        else {
-            value = key.initial?.();
-        }
-        ctx.set(key, value);
-        snapshot.set(key.name, value);
-    }
-    return snapshot;
-}
-/**
- * Commits modified state keys back to `session.state`.
- *
- * Compares each state key's current context value against the snapshot taken
- * during hydration. Only keys whose value changed (reference inequality) are
- * written. Returns the session unchanged when nothing was modified.
- */
-export function commitStateKeys(ctx, session, snapshot) {
-    let newState = null;
-    for (const key of getStateKeys()) {
-        if (ctx.has(key)) {
-            const current = ctx.get(key);
-            if (current !== snapshot.get(key.name)) {
-                if (newState === null) {
-                    newState = { ...session.state };
-                }
-                newState[key.name] = key.codec ? key.codec.serialize(current) : current;
-            }
-        }
-    }
-    if (newState !== null) {
-        return { ...session, state: newState };
-    }
-    return session;
-}
-//# sourceMappingURL=state.js.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"state.js","sourceRoot":"","sources":["../../../src/context/state.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAQxC;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,GAAe,EACf,OAAuB;IAEvB,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAmB,CAAC;IAC5C,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,EAAE,CAAC;QACjC,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,KAAc,CAAC;QACnB,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;QAClE,CAAC;aAAM,CAAC;YACN,KAAK,GAAG,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC;QAC1B,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACpB,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,GAAe,EACf,OAAuB,EACvB,QAAuB;IAEvB,IAAI,QAAQ,GAAmC,IAAI,CAAC;IACpD,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,EAAE,CAAC;QACjC,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACjB,MAAM,OAAO,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC7B,IAAI,OAAO,KAAK,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBACvC,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;oBACtB,QAAQ,GAAG,EAAE,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;gBAClC,CAAC;gBACD,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;YAC1E,CAAC;QACH,CAAC;IACH,CAAC;IACD,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,OAAO,EAAE,GAAG,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;IACzC,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}