experimental-ash 0.34.0 → 0.36.0

package/dist/docs/public/schedules.md

@@ -162,7 +162,7 @@ When a schedule fires, the dispatcher takes one of two paths:
 2. The agent runs in **task mode** with the app principal.
 3. Output is discarded.
 
-In both cases, the schedule session uses the **app principal**: `getSession().auth.current` and `getSession().auth.initiator` are set to `"ash:app"` with `principalType: "runtime"`.
+In both cases, the schedule session uses the **app principal**: `ctx.session.auth.current` and `ctx.session.auth.initiator` are set to `"ash:app"` with `principalType: "runtime"`.
 
 The session goes through the same durable runtime engine as any other Ash session.
 

package/dist/docs/public/session-context.md

@@ -1,42 +1,40 @@
 ---
 title: "Session Context"
-description: "Runtime helpers: getSession, getSandbox, getSkill, and defineState."
+description: "Runtime helpers: ctx.session, ctx.getSandbox, ctx.getSkill, and defineState."
 ---
 
-Ash exposes runtime helpers for authored code:
+Ash exposes runtime state through the `ctx` parameter passed to tool `execute`, hook handlers,
+and channel event handlers:
 
-- `getSession()`
-- `getSandbox()`
-- `getSkill(identifier)`
-- `defineState(name, initial)` -- typed durable state with `get()` and `update()`
+- `ctx.session` -- session metadata, turn, auth, and parent lineage
+- `ctx.getSandbox()` -- live sandbox handle for the current agent
+- `ctx.getSkill(identifier)` -- handle for a named skill visible to the current agent
+- `defineState(name, initial)` -- typed durable state with `get()` and `update()` (imported from `"experimental-ash/context"`)
 
 These APIs work only inside active authored runtime execution such as tools, channel event
 handlers, and authored hooks. They throw when called outside a managed context.
 
-## `getSession()`
+## `ctx.session`
 
-Use `getSession()` when you need durable runtime metadata about the current execution.
+Use `ctx.session` when you need durable runtime metadata about the current execution.
 
 `agent/tools/who_called_me.ts`
 
 ```ts
-import { getSession } from "experimental-ash/context";
 import { defineTool } from "experimental-ash/tools";
 import { z } from "zod";
 
 export default defineTool({
   description: "Return the active session metadata.",
   inputSchema: z.object({}),
-  async execute() {
-    const session = getSession();
-
+  async execute(_input, ctx) {
     return {
-      sessionId: session.sessionId,
-      turnId: session.turn.id,
-      turnSequence: session.turn.sequence,
-      currentCaller: session.auth.current?.principalId,
-      initiator: session.auth.initiator?.principalId,
-      parentSessionId: session.parent?.sessionId,
+      sessionId: ctx.session.id,
+      turnId: ctx.session.turn.id,
+      turnSequence: ctx.session.turn.sequence,
+      currentCaller: ctx.session.auth.current?.principalId,
+      initiator: ctx.session.auth.initiator?.principalId,
+      parentSessionId: ctx.session.parent?.id,
     };
   },
 });
@@ -46,7 +44,7 @@ Public session fields:
 
 - `auth.current`
 - `auth.initiator`
-- `sessionId`
+- `id`
 - `turn.id`
 - `turn.sequence`
 - optional `parent`
@@ -59,13 +57,13 @@ Important behavior:
 - top-level schedule sessions expose the framework app principal (`principalId: "ash:app"`, `principalType: "runtime"`)
 - `parent` is present for child subagent sessions
 
-## `getSandbox()`
+## `ctx.getSandbox()`
 
-`getSandbox()` returns a live handle for the current agent's sandbox.
+`ctx.getSandbox()` returns a live handle for the current agent's sandbox.
 
 ```ts
-const sandbox = await getSandbox();
-const result = await sandbox.runCommand("pnpm test");
+const sandbox = await ctx.getSandbox();
+const result = await sandbox.run({ command: "pnpm test" });
 ```
 
 Important behavior:
@@ -81,12 +79,12 @@ child process.
 
 See [Sandboxes](./sandbox.md) for lifecycle details.
 
-## `getSkill(identifier)`
+## `ctx.getSkill(identifier)`
 
-`getSkill(identifier)` returns a handle for a named skill visible to the current agent.
+`ctx.getSkill(identifier)` returns a handle for a named skill visible to the current agent.
 
 ```ts
-const skill = getSkill("research");
+const skill = ctx.getSkill("research");
 const notes = await skill.file("references/checklist.md").text();
 ```
 
@@ -151,7 +149,7 @@ import { budget } from "../lib/budget.js";
 
 export default defineHook({
   lifecycle: {
-    turn() {
+    turn(ctx) {
       // Reset budget each turn
       budget.update(() => ({ count: 0, cap: 25 }));
     },
@@ -175,7 +173,7 @@ export default defineHook({
 
 Safe places:
 
-- inside `defineTool(...).execute(...)`
+- inside `defineTool(...).execute(input, ctx)`
 - inside authored callbacks Ash runs inside the runtime
 - after asynchronous boundaries inside the same authored execution chain
 

package/dist/docs/public/skills.md

@@ -77,18 +77,17 @@ Packaged skills are useful when you want files like:
 - `scripts/`
 - example inputs or templates
 
-Inside authored runtime code, you can read those packaged files through `getSkill(identifier)`.
+Inside authored runtime code, you can read those packaged files through `ctx.getSkill(identifier)`.
 
 ```ts
-import { getSkill } from "experimental-ash/skills";
 import { defineTool } from "experimental-ash/tools";
 import { z } from "zod";
 
 export default defineTool({
   description: "Load a packaged skill reference file.",
   inputSchema: z.object({}),
-  async execute() {
-    const research = getSkill("research");
+  async execute(_input, ctx) {
+    const research = ctx.getSkill("research");
     return await research.file("references/checklist.md").text();
   },
 });

package/dist/docs/public/subagents.md

@@ -108,7 +108,7 @@ Subagent execution gets:
 - its own tools
 - its own sandbox (independent of the parent's sandbox)
 - its own `skills/` set (independent of the parent's skills)
-- immediate parent lineage in `getSession().parent`
+- immediate parent lineage in `ctx.session.parent`
 
 Skills and sandboxes do not cross the parent/child boundary. The subagent only sees skills
 authored under `agent/subagents/<id>/skills/`; skills under the root `agent/skills/` are not

package/dist/docs/public/tools.md

@@ -13,7 +13,6 @@ back.
 `agent/tools/get_weather.ts`
 
 ```ts
-import { getSession } from "experimental-ash/context";
 import { defineTool } from "experimental-ash/tools";
 import { z } from "zod";
 
@@ -22,12 +21,10 @@ export default defineTool({
   inputSchema: z.object({
     city: z.string(),
   }),
-  async execute(input) {
-    const session = getSession();
-
+  async execute(input, ctx) {
     return {
       city: input.city,
-      sessionId: session.sessionId,
+      sessionId: ctx.session.id,
       temperatureF: 72,
     };
   },
@@ -40,17 +37,17 @@ There is no `name` override and no compile-time normalization — if you want a
 identifier, name the file in snake_case.
 
 `defineTool`, `disableTool`, `defineBashTool`, `defineReadFileTool`, and `defineWriteFileTool` live on the `experimental-ash/tools` subpath.
-Runtime context helpers (`getSession`, `defineState`) live on `experimental-ash/context`.
-`getSandbox` lives on `experimental-ash/sandbox` and `getSkill` lives on `experimental-ash/skills`.
+`defineState` lives on `experimental-ash/context`. Session metadata, sandbox access, and skill access
+are available through the `ctx` parameter passed to `execute`.
 
 ## What A Tool Definition Needs
 
 - a filename slug under `agent/tools/` (this is the model-facing tool name)
 - `description`
 - `inputSchema` — a Zod schema (or any Standard Schema). Required, matching the AI SDK's `Tool` contract. For a tool with no input, pass `z.object({})`.
-- `execute(input, options?)` — the tool's implementation. `options` provides `toolCallId`, `messages`, and `abortSignal` from the AI SDK.
+- `execute(input, ctx)` — the tool's implementation. `ctx` provides session metadata, sandbox access, and skill access.
 
-The AI SDK uses `inputSchema` to validate and transform model input (including Zod defaults) and to type `execute(input)`.
+The AI SDK uses `inputSchema` to validate and transform model input (including Zod defaults) and to type the `input` parameter in `execute(input, ctx)`.
 
 ## Schemas
 
@@ -75,14 +72,13 @@ export default defineTool({
 
 ## Runtime Helpers Inside Tools
 
-Tools are the most common place to use Ash's runtime helpers:
+The `ctx` parameter passed to `execute` is the primary way to access runtime state:
 
-- `getSession()` for session, turn, auth, and parent lineage data
-- `getSandbox()` for the live sandbox handle
-- `getSkill(identifier)` for reading skill metadata and packaged skill files
+- `ctx.session` for session metadata, turn, auth, and parent lineage data
+- `ctx.getSandbox()` for the live sandbox handle
+- `ctx.getSkill(identifier)` for reading skill metadata and packaged skill files
 
-Those APIs only work inside active authored runtime execution. They throw during top-level module
-evaluation.
+These are available inside `execute` and other active authored runtime execution contexts.
 
 ## When A Tool Runs
 
@@ -131,9 +127,9 @@ import { bash } from "experimental-ash/tools/defaults";
 
 export default defineTool({
   ...bash,
-  async execute(input) {
+  async execute(input, ctx) {
     console.log("[bash]", input);
-    return bash.execute(input);
+    return bash.execute(input, ctx);
   },
 });
 ```

package/dist/docs/public/typescript-api.md

@@ -50,11 +50,12 @@ Most apps use `defineAgent`, `defineTool`, and `defineSandbox` the most.
 
 ## Runtime Helpers
 
-Each runtime accessor lives on the subpath that owns its concern:
+Session metadata, sandbox access, and skill access are available through the `ctx` parameter
+passed to tool `execute`, hook handlers, and channel event handlers:
 
-- `getSession()` - current session, turn, auth, and optional parent lineage (`experimental-ash/context`)
-- `getSandbox()` - live sandbox handle for the current agent (`experimental-ash/sandbox`)
-- `getSkill(identifier)` - handle for a named skill visible to the current agent (`experimental-ash/skills`)
+- `ctx.session` - current session, turn, auth, and optional parent lineage
+- `ctx.getSandbox()` - live sandbox handle for the current agent
+- `ctx.getSkill(identifier)` - handle for a named skill visible to the current agent
 - `defineState(name, initial)` - typed durable state with `get()` and `update()` (`experimental-ash/context`)
 
 Related exported types by subpath:
@@ -154,7 +155,7 @@ Channel types exported from `experimental-ash/channels`:
 - `POST` - route helper for POST endpoints
 - `GET` - route helper for GET endpoints
 - `Session` - session handle returned by `send()`
-- `SessionHandle` - read-only session handle from `getSession()`
+- `SessionHandle` - read-only session handle available as `ctx.session`
 - `SendOptions` - options for `send(message, options)`
 
 `RunMode` is explicit: `"conversation"` sessions may wait for follow-up input, while `"task"`
@@ -199,14 +200,12 @@ Event handlers on the channel config receive typed event data:
 ### Typed Tool
 
 ```ts
-import { getSession } from "experimental-ash/context";
 import { defineTool } from "experimental-ash/tools";
 ```
 
 ### Sandbox Access
 
 ```ts
-import { getSandbox } from "experimental-ash/sandbox";
 import { defineTool } from "experimental-ash/tools";
 import { defineBashTool } from "experimental-ash/tools";
 ```
@@ -214,7 +213,7 @@ import { defineBashTool } from "experimental-ash/tools";
 ### Skill Access
 
 ```ts
-import { defineSkill, getSkill } from "experimental-ash/skills";
+import { defineSkill } from "experimental-ash/skills";
 ```
 
 ### Wrapping Or Disabling A Framework Default
@@ -254,9 +253,9 @@ import { Braintrust } from "experimental-ash/evals/reporters";
 - `defineChannel` and channel factories -> [Channels](./channels/README.md)
 - `defineTool`, `disableTool`, `defineBashTool`, `defineReadFileTool`, `defineWriteFileTool`, and `experimental-ash/tools/defaults` -> [Tools](./tools.md)
 - `defineHook`, `HookContext`, and lifecycle/event types -> [Hooks](./hooks.md)
-- `defineSandbox` and `getSandbox` -> [Sandboxes](./sandbox.md)
-- `defineSkill` and `getSkill` -> [Skills](./skills.md)
-- `getSession` -> [Session Context](./session-context.md)
+- `defineSandbox` and `ctx.getSandbox()` -> [Sandboxes](./sandbox.md)
+- `defineSkill` and `ctx.getSkill()` -> [Skills](./skills.md)
+- `ctx.session` -> [Session Context](./session-context.md)
 - subagents (authored with `defineAgent` under `subagents/<id>/agent.ts`) -> [Subagents](./subagents.md)
 - `defineSchedule` -> [Schedules](./schedules.md)
 - `defineEvalSuite`, loaders, reporters, and scorers -> [Evals](./evals.md)

package/dist/src/channel/session.d.ts

@@ -1,6 +1,7 @@
 import type { ContextAccessor } from "#context/key.js";
 import type { HandleMessageStreamEvent } from "#protocol/message.js";
-import type { Runtime, SessionAuthContext } from "#channel/types.js";
+import type { Runtime } from "#channel/types.js";
+import type { SessionAuth } from "#context/keys.js";
 export interface Session {
     readonly id: string;
     readonly continuationToken: string;
@@ -18,35 +19,8 @@ export interface Session {
  */
 export interface SessionHandle {
     readonly id: string;
-    /**
-     * Runtime-scoped continuation token (`<channelName>:<channel-local-token>`).
-     */
     readonly continuationToken: string;
-    readonly auth: SessionAuthContext | null;
-    readonly initiatorAuth: SessionAuthContext | null;
-    /**
-     * Re-key the session under a new continuation token.
-     *
-     * Use this when the channel's resume address depends on data
-     * produced during the turn (e.g. Slack auto-anchoring its first
-     * post adopts the post's `ts` as the thread root). Pass the
-     * channel-local raw token, matching the token shape accepted by
-     * route `send()`; the session handle preserves the current channel
-     * namespace before writing to runtime context.
-     *
-     * Effects:
-     *
-     * - Updates `ContinuationTokenKey` in the active context to the
-     *   runtime-scoped token (`<channelName>:<rawToken>`).
-     * - Causes the workflow runtime to dispose its current park hook
-     *   and register a new one at the new token at the next step
-     *   boundary, so follow-up `deliver` calls keyed under the new
-     *   token resume the same session.
-     * - Idempotent — calling with the current token is a no-op.
-     *
-     * The session must already have a namespaced placeholder
-     * continuation token so the handle can preserve the channel name.
-     */
+    readonly auth: SessionAuth;
     setContinuationToken(rawToken: string): void;
 }
 export declare function createSession(id: string, continuationToken: string, runtime: Runtime): Session;

package/dist/src/channel/session.js

@@ -1 +1 @@
-import{AuthKey,ContinuationTokenKey,InitiatorAuthKey,SessionIdKey}from"#context/keys.js";function createSession(e,t,n){return{id:e,continuationToken:t,async getEventStream(t){return n.getEventStream(e,t)}}}function createGetSessionFn(e){return t=>createSession(t,``,e)}function buildSessionHandle(i){return{get id(){return i.get(SessionIdKey)??``},get continuationToken(){return i.get(ContinuationTokenKey)??``},get auth(){return i.get(AuthKey)??null},get initiatorAuth(){return i.get(InitiatorAuthKey)??null},setContinuationToken(e){let n=i.get(ContinuationTokenKey)??``,r=namespaceContinuationToken(n,e);n!==r&&i.set(ContinuationTokenKey,r)}}}function namespaceContinuationToken(e,t){let n=e.indexOf(`:`);if(n<=0)throw Error(`Cannot set session continuation token without an existing namespaced continuation token. Start the session with a placeholder continuationToken.`);return`${e.slice(0,n+1)}${t}`}export{buildSessionHandle,createGetSessionFn,createSession};
+import{AuthKey,ContinuationTokenKey,InitiatorAuthKey,SessionIdKey}from"#context/keys.js";function createSession(e,t,n){return{id:e,continuationToken:t,async getEventStream(t){return n.getEventStream(e,t)}}}function createGetSessionFn(e){return t=>createSession(t,``,e)}function buildSessionHandle(i){return{get id(){return i.get(SessionIdKey)??``},get continuationToken(){return i.get(ContinuationTokenKey)??``},get auth(){return{current:i.get(AuthKey)??null,initiator:i.get(InitiatorAuthKey)??null}},setContinuationToken(e){let n=i.get(ContinuationTokenKey)??``,r=namespaceContinuationToken(n,e);n!==r&&i.set(ContinuationTokenKey,r)}}}function namespaceContinuationToken(e,t){let n=e.indexOf(`:`);if(n<=0)throw Error(`Cannot set session continuation token without an existing namespaced continuation token. Start the session with a placeholder continuationToken.`);return`${e.slice(0,n+1)}${t}`}export{buildSessionHandle,createGetSessionFn,createSession};

package/dist/src/compiled/.vendor-stamp.json

@@ -20,11 +20,11 @@
     "@standard-schema/spec": "1.1.0",
     "turndown": "7.2.4",
     "@vercel/oidc": "3.4.1",
-    "@vercel/sandbox": "2.0.0",
+    "@vercel/sandbox": "2.0.1",
     "@workflow/core": "5.0.0-beta.7",
     "@workflow/errors": "5.0.0-beta.4",
     "zod": "4.4.3",
     "zod-validation-error": "5.0.0"
   },
-  "scriptHash": "d4ce5a47e0f6620d682bfcba879a1eabaa5c61cc9c9cfe24e3a54c38aaf1edb0"
+  "scriptHash": "de60e990328c8664beec98bc5e81625ecdc0cdace1ba8bd8aa267bf9bea29af4"
 }

package/dist/src/compiled/@vercel/sandbox/index.d.ts

@@ -41,6 +41,7 @@ export interface SandboxCreateOptions {
   env?: Record<string, string> | undefined;
   name?: string | undefined;
   networkPolicy?: NetworkPolicy | undefined;
+  onResume?: ((sandbox: Sandbox) => Promise<void>) | undefined;
   persistent?: boolean | undefined;
   ports?: number[] | undefined;
   resources?: { vcpus?: number | undefined } | undefined;
@@ -52,6 +53,13 @@ export interface SandboxCreateOptions {
   timeout?: number | undefined;
 }
 
+export interface SandboxGetOptions {
+  name: string;
+  onResume?: ((sandbox: Sandbox) => Promise<void>) | undefined;
+  resume?: boolean | undefined;
+  signal?: AbortSignal | undefined;
+}
+
 export interface SandboxRunCommandParams {
   args?: readonly string[] | undefined;
   cmd: string;
@@ -95,9 +103,10 @@ export declare class Sandbox {
   status: string;
   tags?: Record<string, string> | undefined;
   static create(options?: SandboxCreateOptions): Promise<Sandbox>;
-  static get(options: { name: string } | Record<string, unknown>): Promise<Sandbox>;
+  static get(options: SandboxGetOptions): Promise<Sandbox>;
   domain(port: number): string;
-  readFileToBuffer(input: { path: string }): Promise<Buffer | Uint8Array | null>;
+  readFile(file: { path: string }): Promise<ReadableStream<Uint8Array> | null>;
+  readFileToBuffer(file: { path: string }): Promise<Buffer | null>;
   runCommand(input: SandboxRunCommandParams & { detached: true }): Promise<SandboxCommand>;
   runCommand(input: SandboxRunCommandParams): Promise<SandboxCommandFinished>;
   snapshot(options?: unknown): Promise<{ snapshotId: string }>;