experimental-ash 0.35.0 → 0.37.0

package/dist/docs/public/{session-context.md → advanced/session-context.md}

@@ -1,42 +1,41 @@
 ---
 title: "Session Context"
-description: "Runtime helpers: getSession, getSandbox, getSkill, and defineState."
+description: "Runtime helpers: ctx.session, ctx.getSandbox, ctx.getSkill, and defineState."
+url: /session-context
 ---
 
-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 +45,7 @@ Public session fields:
 
 - `auth.current`
 - `auth.initiator`
-- `sessionId`
+- `id`
 - `turn.id`
 - `turn.sequence`
 - optional `parent`
@@ -59,12 +58,12 @@ 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 sandbox = await ctx.getSandbox();
 const result = await sandbox.run({ command: "pnpm test" });
 ```
 
@@ -81,12 +80,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 +150,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 +174,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/{typescript-api.md → advanced/typescript-api.md}

@@ -1,6 +1,7 @@
 ---
 title: "TypeScript API"
 description: "TypeScript API: defineAgent, defineTool, defineSandbox, and all runtime helpers."
+url: /typescript-api
 ---
 
 This page is the quick reference for Ash's public TypeScript surface.
@@ -50,11 +51,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 +156,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 +201,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 +214,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 +254,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/docs/public/{vercel-deployment.md → advanced/vercel-deployment.md}

@@ -1,6 +1,7 @@
 ---
 title: "Vercel Deployment"
 description: "Deploy your agent to Vercel."
+url: /vercel-deployment
 ---
 
 Ash is designed to run locally and on Vercel.

package/dist/docs/public/{workspace.md → advanced/workspace.md}

@@ -1,6 +1,7 @@
 ---
 title: "Workspace"
 description: "Shared filesystem state and the default workspace."
+url: /workspace
 ---
 
 Every Ash session gets a shared runtime workspace exposed to the model as the `bash` tool.

package/dist/docs/public/channels/{README.md → index.md}

@@ -179,7 +179,7 @@ export default slackChannel({
       if (event.finishReason === "tool-calls") return;
       if (event.message) ctx.thread.post(event.message);
     },
-    "session.failed"(event, ctx) {
+    "session.failed"(_event, ctx) {
       ctx.thread.post("Something went wrong.");
     },
   },
@@ -372,7 +372,7 @@ Semantics:
 
 - The target channel's authored `receive(input, { send })` hook owns the continuation-token
   format and the initial state. Callers supply only `{ message, args, auth }`.
-- `auth` flows through to `session.initiatorAuth` so the target's event handlers and the
+- `auth` flows through to `session.auth.initiator` so the target's event handlers and the
   agent's tools can read who started the session.
 - Calling `args.receive(...)` does **not** also start a session on the current channel. The
   inbound channel's response is whatever the route handler returns explicitly (e.g.

package/dist/docs/public/channels/slack.md

@@ -163,7 +163,7 @@ export default slackChannel({
       if (event.finishReason === "tool-calls") return;
       if (event.message) ctx.thread.post(event.message);
     },
-    "session.failed"(event, ctx) {
+    "session.failed"(_event, ctx) {
       ctx.thread.post("Something went wrong.");
     },
   },
@@ -194,8 +194,8 @@ export default slackChannel({
   webhook side via `waitUntil`, so the channel returns `200 OK` to Slack immediately.
 
 `events: { ... }` handlers receive runtime events emitted by the harness after the turn dispatches
-(`turn.started`, `message.completed`, `session.failed`, etc.). They run inside the workflow context,
-not on the inbound webhook side.
+(`turn.started`, `message.completed`, `session.failed`, etc.). They receive `(eventData, ctx)` and
+run inside the workflow context, not on the inbound webhook side.
 
 ### Thread Context
 

package/dist/docs/public/meta.json

@@ -2,30 +2,17 @@
   "pages": [
     "getting-started",
     "---",
-    "project-layout",
     "agent-ts",
-    "context-control",
     "skills",
     "tools",
-    "hooks",
     "human-in-the-loop",
     "sandbox",
     "channels",
-    "auth-and-route-protection",
     "subagents",
     "schedules",
     "connections",
     "---",
-    "vercel-deployment",
-    "runs-and-streaming",
-    "session-context",
-    "workspace",
-    "evals",
-    "instrumentation",
-    "cli-build-and-debugging",
-    "typescript-api",
-    "...",
-    "faqs",
+    "advanced",
     "---",
     "research"
   ]

package/dist/docs/public/sandbox.md

@@ -114,18 +114,17 @@ and `write_file` tools. The runtime name comes from the file stem (here, `repo_s
 ## Using The Sandbox From Authored Code
 
 Any authored runtime function (tool, step, or model callback) can bind a live sandbox handle via
-`getSandbox()`:
+`ctx.getSandbox()`:
 
 ```ts
-import { getSandbox } from "experimental-ash/sandbox";
 import { defineTool } from "experimental-ash/tools";
 import { z } from "zod";
 
 export default defineTool({
   description: "Append an analytics event to the running session log.",
   inputSchema: z.object({ kind: z.string(), payload: z.string() }),
-  async execute({ kind, payload }) {
-    const sandbox = await getSandbox();
+  async execute({ kind, payload }, ctx) {
+    const sandbox = await ctx.getSandbox();
     await sandbox.run({
       command: `echo ${JSON.stringify(JSON.stringify({ kind, payload }))} >> /var/lib/analytics/events.log`,
     });
@@ -136,7 +135,7 @@ export default defineTool({
 
 Important rules:
 
-- `getSandbox()` takes no arguments and is async.
+- `ctx.getSandbox()` takes no arguments and is async.
 - It only works inside authored runtime execution.
 - Visibility is node-local: the root agent sees the root agent's sandbox; a local subagent sees its
   own sandbox, not the parent's.
@@ -154,7 +153,7 @@ Use it when you need an absolute path to interpolate into a generated command or
 hardcoding `/workspace/` yourself:
 
 ```ts
-const sandbox = await getSandbox();
+const sandbox = await ctx.getSandbox();
 const analysisRoot = sandbox.resolvePath("python-analysis");
 
 await sandbox.writeFile("python-analysis/run.py", "print('ok')\n");
@@ -176,7 +175,7 @@ different skills, so they should not inherit the parent's filesystem.
   with that workspace seeded in.
 - If a subagent authors neither, the framework default is used as-is.
 
-Inside a subagent's authored code, `getSandbox()` binds to the subagent's own sandbox.
+Inside a subagent's authored code, `ctx.getSandbox()` binds to the subagent's own sandbox.
 
 ## Lifecycle Semantics
 
@@ -210,18 +209,17 @@ returned. The accepted option shape is whatever the backend's update call accept
 factory; `onSession`'s `use()` overrides any overlapping fields post-create.
 
 Unlike `bootstrap`, `onSession` runs inside the active Ash runtime context, so user-scoped setup can
-call `getSession()` and derive the current principal without baking credentials into the reusable
+read `ctx.session` and derive the current principal without baking credentials into the reusable
 template:
 
 ```ts
-import { getSession } from "experimental-ash/context";
 import { defineSandbox, vercelBackend } from "experimental-ash/sandbox";
 
 export default defineSandbox({
   backend: vercelBackend(),
-  async onSession({ use }) {
+  async onSession({ use, ctx }) {
     const sandbox = await use({ networkPolicy: "deny-all" });
-    const user = getSession().auth.current;
+    const user = ctx.session.auth.current;
     if (user === null) return;
 
     await sandbox.writeFile(

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/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/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/context/accessors.d.ts

@@ -1,23 +1,5 @@
-import type { SkillHandle } from "#execution/skills/types.js";
-import type { SandboxSession } from "#public/definitions/sandbox.js";
 import type { ContextKey } from "#context/key.js";
-import { type Session } from "#context/keys.js";
 export type { Session, SessionAuth, SessionAuthContext, SessionParent, SessionTurn, } from "#context/keys.js";
-/**
- * Returns the active session for the current authored async execution chain.
- *
- * @throws When called outside of a managed step execution.
- */
-export declare function getSession(): Session;
-/**
- * Returns the active sandbox session for the current runtime execution.
- *
- * Each agent owns exactly one sandbox; callers do not pass a name.
- *
- * @throws When called outside of a managed step execution or when the
- *   sandbox is not available on the current context.
- */
-export declare function getSandbox(): Promise<SandboxSession>;
 /**
  * Returns the current value of a context key, or `undefined` when unset.
  *
@@ -56,10 +38,3 @@ export declare function setContext<T>(key: ContextKey<T>, valueOrUpdater: T | ((
  * @throws When called outside of a managed step execution.
  */
 export declare function ensureContext<T>(key: ContextKey<T>, create: () => T): T;
-/**
- * Returns a handle for the named skill visible to the current agent.
- *
- * @throws When called outside of a managed step execution or when the
- *   requested skill is not found.
- */
-export declare function getSkill(identifier: string): SkillHandle;

package/dist/src/context/accessors.js

@@ -1 +1 @@
-import{SandboxKey,SessionKey}from"#context/keys.js";import{createSandboxSkillHandle}from"#runtime/skills/sandbox-access.js";import{loadContext}from"#context/container.js";function getSession(){return loadContext().require(SessionKey)}async function getSandbox(){let t=loadContext().get(SandboxKey);if(t===void 0)throw Error(`Ash sandbox runtime access is unavailable in the current async context. Call getSandbox() only from authored runtime functions such as tools, steps, and model callbacks.`);let n=await t.get();if(n===null)throw Error(`The sandbox is not available in the current authored runtime context.`);return n}function getContext(e){return loadContext().get(e)}function requireContext(e){return loadContext().require(e)}function hasContext(e){return loadContext().has(e)}function setContext(e,t){return loadContext().set(e,t)}function ensureContext(e,t){return loadContext().ensure(e,t)}function getSkill(t){let r=loadContext().get(SandboxKey);if(r===void 0)throw Error(`Ash sandbox runtime access is unavailable in the current async context. Call getSkill() only from authored runtime functions such as tools, steps, and model callbacks.`);return createSandboxSkillHandle(r,t)}export{ensureContext,getContext,getSandbox,getSession,getSkill,hasContext,requireContext,setContext};
+import{loadContext}from"#context/container.js";function getContext(e){return loadContext().get(e)}function requireContext(e){return loadContext().require(e)}function hasContext(e){return loadContext().has(e)}function setContext(e,t){return loadContext().set(e,t)}function ensureContext(e,t){return loadContext().ensure(e,t)}export{ensureContext,getContext,hasContext,requireContext,setContext};

package/dist/src/context/build-callback-context.d.ts

@@ -0,0 +1,8 @@
+import type { AshCallbackContext } from "#public/definitions/callback-context.js";
+/**
+ * Builds an {@link AshCallbackContext} from the active ALS scope.
+ *
+ * Must be called inside a harness step (active `contextStorage.run`).
+ * Throws when called outside an ALS scope.
+ */
+export declare function buildCallbackContext(): AshCallbackContext;

package/dist/src/context/build-callback-context.js

@@ -0,0 +1 @@
+import{SandboxKey,SessionKey}from"#context/keys.js";import{loadContext}from"#context/container.js";import{createSandboxSkillHandle}from"#runtime/skills/sandbox-access.js";function buildCallbackContext(){let r=loadContext(),i=r.require(SessionKey);return{session:{id:i.sessionId,auth:i.auth,turn:i.turn,parent:i.parent},getSandbox(){let t=r.get(SandboxKey);if(t===void 0)throw Error(`Ash sandbox runtime access is unavailable in the current async context. Call ctx.getSandbox() only from authored runtime functions such as tools, hooks, and channel events.`);return t.get().then(e=>{if(e===null)throw Error(`The sandbox is not available in the current authored runtime context.`);return e})},getSkill(t){let n=r.get(SandboxKey);if(n===void 0)throw Error(`Ash sandbox runtime access is unavailable in the current async context. Call ctx.getSkill() only from authored runtime functions such as tools, hooks, and channel events.`);return createSandboxSkillHandle(n,t)}}}export{buildCallbackContext};

package/dist/src/context/hook-lifecycle.js

@@ -1 +1 @@
-import{ContinuationTokenKey,SandboxKey,SessionIdKey,SessionPreparedKey}from"./keys.js";import{createLogger}from"#internal/logging.js";import{toErrorMessage}from"#shared/errors.js";import{normalizeSkillPackage,writeSkillPackageToSandbox}from"#shared/skill-package.js";import{getAdapterKind}from"#channel/adapter.js";import{emitRecoverableFailedTurn,emitTurnPreamble,getHarnessEmissionState,setHarnessEmissionState}from"#harness/emission.js";import{formatAvailableSkillsSection}from"#execution/skills/instructions.js";import{BundleKey,ChannelKey}from"#runtime/sessions/runtime-context-keys.js";const log=createLogger(`hooks.lifecycle`);async function dispatchHookLifecycle(e){let{ctx:t,registry:n,emit:i}=e,o=getHarnessEmissionState(e.session.state),s=`turn_${o.sequence}`,c=o.sequence,l=buildHookContext(t),u={session:{sessionId:e.session.sessionId},turn:{sequence:c,turnId:s}},d=[],f=e.session;if(n.session.length>0&&t.get(SessionPreparedKey)!==!0){t.set(SessionPreparedKey,!0);let e=[];for(let r of n.session){let n=await r.handler(u,l);n?.modelContext!==void 0&&n.modelContext.length>0&&d.push(...n.modelContext),e.push(...normalizeLifecycleSkillResults(t,n))}f=await materializeLifecycleSkills(t,f,e)}let p=!1,m=o;try{let e=[];for(let r of n.turn){let n=await r.handler(u,l);n?.modelContext!==void 0&&n.modelContext.length>0&&d.push(...n.modelContext),e.push(...normalizeLifecycleSkillResults(t,n))}f=await materializeLifecycleSkills(t,f,e)}catch(t){let n=toErrorMessage(t);try{p||=(m=await emitTurnPreamble(i,{message:e.input.message},o,e.runtimeIdentity),!0);let t=await emitRecoverableFailedTurn(i,m,{code:`HOOK_TURN_FAILED`,message:n});return{kind:`turn-failed`,message:n,nextSession:setHarnessEmissionState(f,t)}}catch(e){throw log.error(`Event hook threw while emitting the turn.failed cascade for a lifecycle.turn failure — escalating to session.failed.`,{error:toErrorMessage(e)}),e}}let h=e.input.modelContext??[],g=h.length===0?d:[...h,...d];return{kind:`proceed`,input:g.length>0?{...e.input,modelContext:g}:e.input,nextSession:f}}function normalizeLifecycleSkillResults(e,t){if(t?.skills===void 0||t.skills.length===0)return[];let n=new Set(e.require(BundleKey).resolvedAgent.skills.map(e=>e.name)),r=new Map;for(let e of t.skills){let t=normalizeSkillPackage(e);if(n.has(t.name))throw Error(`Hook-contributed skill "${t.name}" conflicts with an authored skill.`);r.set(t.name,t)}return[...r.values()]}async function materializeLifecycleSkills(e,n,r){if(r.length===0)return n;let i=new Map(r.map(e=>[e.name,e])),a=await e.require(SandboxKey).get();if(a===null)throw Error(`Dynamic skills require a sandbox for the current agent.`);for(let e of i.values())await writeSkillPackageToSandbox({sandbox:a,skill:e});let o=formatAvailableSkillsSection([...i.values()]);return o===null?n:{...n,history:[...n.history,{role:`system`,content:o}]}}async function dispatchStreamEventHooks(e){let t=e.registry.streamEventsByType.get(e.event.type)??[],n=e.registry.streamEventsWildcard;if(t.length===0&&n.length===0)return;let r=buildHookContext(e.ctx);for(let n of t)await n.handler(e.event,r);for(let t of n)await t.handler(e.event,r)}function buildHookContext(t){let r=t.require(BundleKey),i=t.get(ChannelKey),a=t.get(ContinuationTokenKey),o=i===void 0?void 0:getAdapterKind(i);return{agent:{name:r.resolvedAgent.config.name??`agent`,nodeId:r.nodeId},channel:{kind:o,continuationToken:a},session:{sessionId:t.get(SessionIdKey)??``},ash:t}}async function runHookLifecycleStep(e,t){let n=await dispatchHookLifecycle(e);return n.kind===`turn-failed`?{next:e.mode===`conversation`?null:{done:!0,output:n.message},session:n.nextSession}:t(n.nextSession,n.input)}export{dispatchHookLifecycle,dispatchStreamEventHooks,runHookLifecycleStep};
+import{ContinuationTokenKey,SandboxKey,SessionPreparedKey}from"./keys.js";import{createLogger}from"#internal/logging.js";import{toErrorMessage}from"#shared/errors.js";import{normalizeSkillPackage,writeSkillPackageToSandbox}from"#shared/skill-package.js";import{getAdapterKind}from"#channel/adapter.js";import{emitRecoverableFailedTurn,emitTurnPreamble,getHarnessEmissionState,setHarnessEmissionState}from"#harness/emission.js";import{formatAvailableSkillsSection}from"#execution/skills/instructions.js";import{buildCallbackContext}from"#context/build-callback-context.js";import{BundleKey,ChannelKey}from"#runtime/sessions/runtime-context-keys.js";const log=createLogger(`hooks.lifecycle`);async function dispatchHookLifecycle(e){let{ctx:t,registry:r,emit:a}=e,o=getHarnessEmissionState(e.session.state),s=buildHookContext(t),c=[],l=e.session;if(r.session.length>0&&t.get(SessionPreparedKey)!==!0){t.set(SessionPreparedKey,!0);let e=[];for(let n of r.session){let r=await n.handler(s);r?.modelContext!==void 0&&r.modelContext.length>0&&c.push(...r.modelContext),e.push(...normalizeLifecycleSkillResults(t,r))}l=await materializeLifecycleSkills(t,l,e)}let u=!1,d=o;try{let e=[];for(let n of r.turn){let r=await n.handler(s);r?.modelContext!==void 0&&r.modelContext.length>0&&c.push(...r.modelContext),e.push(...normalizeLifecycleSkillResults(t,r))}l=await materializeLifecycleSkills(t,l,e)}catch(t){let n=toErrorMessage(t);try{u||=(d=await emitTurnPreamble(a,{message:e.input.message},o,e.runtimeIdentity),!0);let t=await emitRecoverableFailedTurn(a,d,{code:`HOOK_TURN_FAILED`,message:n});return{kind:`turn-failed`,message:n,nextSession:setHarnessEmissionState(l,t)}}catch(e){throw log.error(`Event hook threw while emitting the turn.failed cascade for a lifecycle.turn failure — escalating to session.failed.`,{error:toErrorMessage(e)}),e}}let f=e.input.modelContext??[],p=f.length===0?c:[...f,...c];return{kind:`proceed`,input:p.length>0?{...e.input,modelContext:p}:e.input,nextSession:l}}function normalizeLifecycleSkillResults(e,t){if(t?.skills===void 0||t.skills.length===0)return[];let n=new Set(e.require(BundleKey).resolvedAgent.skills.map(e=>e.name)),r=new Map;for(let e of t.skills){let t=normalizeSkillPackage(e);if(n.has(t.name))throw Error(`Hook-contributed skill "${t.name}" conflicts with an authored skill.`);r.set(t.name,t)}return[...r.values()]}async function materializeLifecycleSkills(e,n,r){if(r.length===0)return n;let i=new Map(r.map(e=>[e.name,e])),a=await e.require(SandboxKey).get();if(a===null)throw Error(`Dynamic skills require a sandbox for the current agent.`);for(let e of i.values())await writeSkillPackageToSandbox({sandbox:a,skill:e});let s=formatAvailableSkillsSection([...i.values()]);return s===null?n:{...n,history:[...n.history,{role:`system`,content:s}]}}async function dispatchStreamEventHooks(e){let t=e.registry.streamEventsByType.get(e.event.type)??[],n=e.registry.streamEventsWildcard;if(t.length===0&&n.length===0)return;let r=buildHookContext(e.ctx);for(let n of t)await n.handler(e.event,r);for(let t of n)await t.handler(e.event,r)}function buildHookContext(t){let n=t.require(BundleKey),r=t.get(ChannelKey),i=t.get(ContinuationTokenKey),a=r===void 0?void 0:getAdapterKind(r);return{...buildCallbackContext(),agent:{name:n.resolvedAgent.config.name??`agent`,nodeId:n.nodeId},channel:{kind:a,continuationToken:i}}}async function runHookLifecycleStep(e,t){let n=await dispatchHookLifecycle(e);return n.kind===`turn-failed`?{next:e.mode===`conversation`?null:{done:!0,output:n.message},session:n.nextSession}:t(n.nextSession,n.input)}export{dispatchHookLifecycle,dispatchStreamEventHooks,runHookLifecycleStep};

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

@@ -19,8 +19,8 @@ export interface SessionAuth {
     readonly initiator: SessionAuthContext | null;
 }
 /**
- * Public session metadata exposed to authored code (tools, steps, model
- * callbacks) via {@link getSession}.
+ * Public session metadata exposed to authored code (tools, hooks,
+ * channel events) via `ctx.session`.
  */
 export interface Session {
     readonly auth: SessionAuth;

package/dist/src/evals/define-eval-suite.d.ts

@@ -1,4 +1,5 @@
-import type { AshEvalSuiteDefinition, AshEvalSuiteInput } from "#evals/types.js";
+import type { AshEvalSuiteDefinition, AshEvalSuiteInput, AshEvalSuiteInputFields } from "#evals/types.js";
+import type { ExactDefinition } from "#public/definitions/exact.js";
 /**
  * Defines one Ash eval suite.
  *
@@ -7,4 +8,4 @@ import type { AshEvalSuiteDefinition, AshEvalSuiteInput } from "#evals/types.js"
  * either `load` (an async function) or `cases` (a static array), but not
  * both.
  */
-export declare function defineEvalSuite(input: AshEvalSuiteInput): AshEvalSuiteDefinition;
+export declare function defineEvalSuite<TInput extends AshEvalSuiteInput>(input: ExactDefinition<TInput, AshEvalSuiteInputFields>): AshEvalSuiteDefinition;