experimental-ash 0.18.3 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # experimental-ash
 
+## 0.20.0
+
+### Minor Changes
+
+- d94e73f: feat(ash): add `toModelOutput` on tool definitions
+
+  Tools can now declare a `toModelOutput` function that controls what the model sees as the tool result. The full `execute()` return remains available to channel event handlers and hooks via `action.result` events. Delegates to the AI SDK's native `toModelOutput` support.
+
+- b78ef37: chore(ash): update AI SDK to latest version and align `SandboxSession` definition
+
+### Patch Changes
+
+- a4fab4d: fix(slack): send Slack Web API calls form-encoded.
+
+  `callSlackApi` previously defaulted to `application/json`, which Slack
+  rejects on a subset of methods (notably `conversations.replies`, which
+  backs `SlackThread.refresh()` and the public `loadThreadContextMessages`
+  helper). Calls to those endpoints failed with `invalid_arguments`,
+  leaving `recentMessages` empty on every valid thread reply.
+
+  Slack documents `application/x-www-form-urlencoded` as universally
+  supported and Slack's own SDK uses form encoding exclusively.
+  `callSlackApi` now does the same: the body is always form-encoded, the
+  redundant `encoding: "form"` arguments on the file-upload callsites are
+  removed, and the `encoding` parameter is gone.
+
+- c465274: fix(ash): fix broken Nitro rebuilds due to partial stream trigger
+
+## 0.19.0
+
+### Minor Changes
+
+- bede748: feat(ash): give agent author control over backend specific sandbox creation options
+- 08e8e82: feat(slack): support thread model context
+
 ## 0.18.3
 
 ### Patch Changes

package/dist/docs/internals/context.md

@@ -82,6 +82,13 @@ runs inside step (4)'s ALS scope, before the harness step. See
 [Hooks](./hooks.md) for the full pipeline and the
 `SessionPreparedKey` flag's failure semantics.
 
+`StepInput.modelContext` has two producers. Channels can provide
+ephemeral messages through `SendPayload.modelContext`, and lifecycle
+hooks can provide them through `LifecycleHookResult.modelContext`.
+The merge order is channel first, then `lifecycle.session`, then
+`lifecycle.turn`. The merged messages are visible to the next model
+call only and are never persisted to durable session history.
+
 ## Channel Context
 
 Channels set custom durable context keys inside `onDeliver(ctx, payload)`. The method receives a `ContextAccessor` and returns `Promise<StepInput>`. This runs once per turn (both initial `run()` and each `deliver()`), after auth keys are seeded. Channel code stays workflow-agnostic because it only touches the accessor.

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

@@ -328,6 +328,11 @@ await args.receive(slack, {
 });
 ```
 
+For inbound mentions in an existing Slack thread, `onAppMention` and
+`onDirectMessage` may return `modelContext` to inject fetched thread
+history into the next model call without persisting it. See
+[Slack thread context](/docs/channels/slack#thread-context).
+
 `threadTs` and `initialMessage` are mutually exclusive: pass `threadTs` to join an existing
 thread, or `initialMessage` to anchor a new one. With neither, the first agent post anchors
 the thread automatically.

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

@@ -159,10 +159,12 @@ export default slackChannel({
 - **`onAppMention(ctx, message)`** -- decides whether to dispatch a turn for an inbound
   `app_mention`, with what `auth` context, and runs any pre-dispatch side effects (typing
   indicators, logging, feature-flag lookups). Return `{ auth }` to dispatch or `null` to silently
-  drop the mention. May be sync or async; the framework awaits the result before dispatching.
-  Thrown errors are caught, logged, and drop the mention -- wrap best-effort side effects in
-  `try/catch` if you want them to be non-fatal. The default `onAppMention` derives a
-  workspace-scoped auth from the Slack actor and posts a `"Thinking…"` typing indicator.
+  drop the mention. Return `{ auth, modelContext }` to add ephemeral messages to the next model
+  call without writing them to durable session history. May be sync or async; the framework awaits
+  the result before dispatching. Thrown errors are caught, logged, and drop the mention -- wrap
+  best-effort side effects in `try/catch` if you want them to be non-fatal. The default
+  `onAppMention` derives a workspace-scoped auth from the Slack actor and posts a `"Thinking…"`
+  typing indicator.
 - **`onDirectMessage(ctx, message)`** -- same contract as `onAppMention`, but for direct messages
   (Slack `message` events with `channel_type: "im"`). The framework filters bot-authored messages
   (`bot_id` set, including the bot's own replies) and message subtypes (edits, deletes, joins)
@@ -177,6 +179,58 @@ export default slackChannel({
 (`turn.started`, `message.completed`, `session.failed`, etc.). They run inside the workflow context,
 not on the inbound webhook side.
 
+### Thread Context
+
+When the bot is mentioned in an existing Slack thread, the triggering mention is delivered to the
+agent by default, but prior thread replies are not injected automatically. Fetch thread history in
+`onAppMention` or `onDirectMessage` and return `modelContext` when the agent should see that
+background on the next model call.
+
+Use `since: "last-agent-reply"` for repeated tags in the same thread. It returns only messages
+after the agent's last Slack reply and before the current mention, so the injected context stays
+small and can be modeled as a `role: "user"` message without changing the system prompt.
+
+```ts
+import {
+  defaultSlackAuth,
+  loadThreadContextMessages,
+  slackChannel,
+  type ModelMessage,
+} from "experimental-ash/channels/slack";
+
+export default slackChannel({
+  async onAppMention(ctx, message) {
+    const auth = defaultSlackAuth(message, ctx);
+
+    const priorMessages = await loadThreadContextMessages(ctx.thread, message, {
+      since: "last-agent-reply",
+    });
+    if (priorMessages.length === 0) {
+      return { auth };
+    }
+
+    const transcript = priorMessages
+      .map((entry) => `${entry.isMe ? "you" : (entry.user ?? "user")}: ${entry.markdown}`)
+      .join("\n");
+
+    const modelContext: ModelMessage[] = [
+      {
+        role: "user",
+        content:
+          "Recent Slack thread messages since your last reply, oldest first. " +
+          "Use them as background context for the current mention.\n\n" +
+          transcript,
+      },
+    ];
+
+    return { auth, modelContext };
+  },
+});
+```
+
+`modelContext` is one-shot context: it is used for the model call that dispatches this inbound
+message and is never persisted to `session.history`.
+
 ### Direct Messages
 
 Add `onDirectMessage` alongside `onAppMention` to handle 1:1 DMs:

package/dist/docs/public/hooks.md

@@ -81,8 +81,10 @@ model turn. `lifecycle.turn` runs **once per fresh delivery** — tool-loop
 continuations and HITL resumes do not re-fire it.
 
 Both keys may return `{ modelContext }`. Contributions are concatenated
-session-then-turn-then-this-call before the harness's next model call,
-and are never written to durable history.
+session-then-turn before the harness's next model call, and are never
+written to durable history. Channels may also contribute the same
+`modelContext` shape through `SendPayload`; channel-provided messages
+appear before lifecycle hook messages.
 
 ### Seed durable context
 

package/dist/docs/public/sandbox.md

@@ -53,7 +53,10 @@ The public lifecycle surface is intentionally small:
 - `bootstrap({ use })` — template-scoped setup (runs once when the template is built). Call `use()`
   to get a `SandboxSession` for filesystem setup. Only filesystem state survives snapshotting.
 - `onSession({ use })` — durable-session-scoped setup (runs once per session). Call `use(opts?)` to
-  get the backend-specific sandbox (e.g. `VercelSandbox`) with session-level configuration applied.
+  get a `SandboxSession`; `opts` are forwarded to the backend's update path (the Vercel SDK's
+  `sandbox.update(...)`) before the session is returned. `onSession`'s `use()` never creates a
+  sandbox — creation happens at prewarm time and at first-time session-create, both driven by the
+  backend factory's options.
 - `sandbox.resolvePath(path)` — translate a logical `/workspace/...` path into the live filesystem
 - `sandbox.runCommand(command)` — run a shell command inside the sandbox
 
@@ -200,9 +203,11 @@ template before the authored `bootstrap` runs, so your bootstrap can read them.
 - configuring per-user credentials for CLI tools
 - writing one-time markers
 
-Call `use(opts?)` to get the backend-specific sandbox. When using `vercelBackend()`, this returns
-a `VercelSandbox` with `update()` for session-level configuration. Options passed to `use()` are
-applied immediately; you can call `sandbox.update()` again later if needed.
+Call `use(opts?)` to get a `SandboxSession`. When `opts` are supplied, the backend forwards them
+to its update path (for `vercelBackend()`, this is `sandbox.update(opts)`) before the session is
+returned. The accepted option shape is whatever the backend's update call accepts — `onSession`'s
+`use()` never invokes `Sandbox.create`. Default `Sandbox.create` options come from the backend
+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
@@ -231,9 +236,8 @@ export default defineSandbox({
 
 Ash ships two built-in backends, exposed as factory functions from `experimental-ash/sandbox`:
 
-- `vercelBackend()` — runs the sandbox on Vercel Sandbox via `@vercel/sandbox`. Returns a
-  `VercelSandbox` from `onSession`'s `use()` with full SDK capabilities.
-- `localBackend()` — runs the sandbox locally via `just-bash`. Default for `pnpm ash dev`.
+- `vercelBackend(opts?)` — runs the sandbox on Vercel Sandbox via `@vercel/sandbox`.
+- `localBackend(opts?)` — runs the sandbox locally via `just-bash`. Default for `pnpm ash dev`.
 
 Attach a backend via `defineSandbox({ backend })`:
 
@@ -242,7 +246,7 @@ Attach a backend via `defineSandbox({ backend })`:
 import { defineSandbox, vercelBackend } from "experimental-ash/sandbox";
 
 export default defineSandbox({
-  backend: vercelBackend(),
+  backend: vercelBackend({ runtime: "node24", resources: { vcpus: 2 } }),
   async bootstrap({ use }) {
     const sandbox = await use();
     await sandbox.runCommand("git clone https://example.com/repo.git repo");
@@ -258,76 +262,91 @@ When `backend` is omitted, Ash substitutes `defaultBackend()` at runtime, which
 everywhere else. `pnpm ash dev` on a developer laptop therefore boots the local workspace by
 default; production builds on Vercel use the Vercel backend by default.
 
-If you want the env-aware default explicitly, use `defaultBackend()`:
+`defaultBackend()` also accepts a keyed options bag so each inner backend gets its own typed
+create options without forcing you to pin to one backend up front:
 
 ```ts
 import { defaultBackend, defineSandbox } from "experimental-ash/sandbox";
 
 export default defineSandbox({
-  backend: defaultBackend(),
+  backend: defaultBackend({
+    vercel: { networkPolicy: "deny-all", resources: { vcpus: 4 } },
+    local: {},
+  }),
 });
 ```
 
-### Vercel Backend: Session Configuration
+### Creation Options
 
-`vercelBackend()` takes no options. All configuration is done through lifecycle hooks:
+The factory `opts` parameter is forwarded to the underlying SDK's `Sandbox.create(...)` call for
+every fresh sandbox the framework creates — both the template at prewarm time and the session at
+first-time session-create.
 
-- **Immutable creation config** (runtime, ports, env) — passed via `bootstrap`'s `use()`:
+On resume (when the framework reattaches to an existing persistent session via `Sandbox.get`), no
+`Sandbox.create` call happens, so the factory opts are not re-applied. The existing sandbox keeps
+whatever configuration it had from its prior creation.
 
-```ts
-async bootstrap({ use }) {
-  const sandbox = await use({ runtime: "node24", ports: [3000] });
-  await sandbox.runCommand("npm install");
-}
-```
+Lifecycle hooks remain update-time and override post-create:
+
+- `bootstrap.use(opts)` calls the SDK's `sandbox.update(opts)` on the template, before the
+  snapshot is captured.
+- `onSession.use(opts)` calls `sandbox.update(opts)` on the live session every time it opens.
+
+So `vercelBackend({ networkPolicy: "deny-all" })` paired with no authored hooks puts every fresh
+sandbox in deny-all mode. Adding `onSession({ use }) { await use({ networkPolicy: "allow-all" }); }`
+overrides that for every session open.
+
+The Vercel SDK forbids the `runtime` field when creating from a snapshot, so Ash strips `runtime`
+from session-create calls. `runtime` only takes effect on the template create — the resulting
+snapshot then determines the runtime for every session derived from it.
+
+### Deferring Backend Construction
 
-- **Session-level config** (networkPolicy, resources, timeout, tags) — passed via `onSession`'s
-  `use()` or `sandbox.update()`:
+`SandboxDefinition.backend` also accepts a zero-arg callback that returns a backend. The callback
+fires lazily on first framework access and the result is memoized for the lifetime of the process —
+so backend-internal state (such as the Vercel backend's prewarmed-template cache) is preserved
+across every call. Use this form to defer evaluation, for example when create options depend on
+environment variables that aren't set at module load time:
 
 ```ts
-async onSession({ use }) {
-  const sandbox = await use({
-    networkPolicy: "deny-all",
-    resources: { vcpus: 4 },
-    timeout: 60 * 60 * 1_000,
-  });
-  // Can also update later:
-  await sandbox.update({ tags: { user: "casey" } });
-}
+export default defineSandbox({
+  backend: () => vercelBackend({ env: { TOKEN: process.env.TOKEN ?? "" } }),
+});
 ```
 
-This split ensures that `bootstrap` only does filesystem setup (which survives snapshotting), while
-`onSession` configures the live session (network policy, resources, etc. do not survive snapshots).
-
 ### Network Policies
 
-Network policies are set per-session via `onSession`. Three forms are supported:
+Three forms are supported on both the factory and the hook `use()` calls:
 
 ```ts
-await use({ networkPolicy: "allow-all" }); // default
-await use({ networkPolicy: "deny-all" }); // block all egress, including DNS
+networkPolicy: "allow-all"; // default
+networkPolicy: "deny-all"; // block all egress, including DNS
 
-await use({
-  networkPolicy: {
-    allow: ["ai-gateway.vercel.sh", "*.github.com"],
-    subnets: { deny: ["10.0.0.0/8"] },
-  },
-});
+networkPolicy: {
+  allow: ["ai-gateway.vercel.sh", "*.github.com"],
+  subnets: { deny: ["10.0.0.0/8"] },
+};
 ```
 
-Since network policy is applied in `onSession` (after the template snapshot), it does not constrain
-`bootstrap`. You can freely `git clone` and `npm install` in bootstrap, then lock down the network
-in `onSession`.
+To apply the policy from sandbox creation onward — including during `bootstrap`'s commands —
+pass it to the factory: `vercelBackend({ networkPolicy: "deny-all" })`. To override per-session
+or to apply it only after the template has been built, set it in `onSession`'s `use()`. The
+common pattern: leave the factory open so `bootstrap` can `git clone` and `npm install`, then
+lock down via `onSession`.
 
 ### Timeout
 
 The `@vercel/sandbox` SDK shuts down idle VMs after a configurable timeout (default 5 minutes). Ash
-raises this default to **30 minutes** so the sandbox survives across workflow step boundaries. You can
-override it in `onSession`:
+raises this default to **30 minutes** so the sandbox survives across workflow step boundaries. Set
+a different default on the factory, or override per-session in `onSession`:
 
 ```ts
+// factory default — applies to every fresh sandbox
+backend: vercelBackend({ timeout: 60 * 60 * 1_000 }); // 1 hour
+
+// or override per-session
 async onSession({ use }) {
-  await use({ timeout: 60 * 60 * 1_000 }); // 1 hour
+  await use({ timeout: 60 * 60 * 1_000 });
 }
 ```
 
@@ -342,9 +361,12 @@ Ash attaches Vercel Sandbox tags for runtime attribution:
 - `channel` — the active channel adapter kind
 - `sessionId` — the Ash session id
 
-Custom tags can be set via `onSession`:
+Custom tags can be set on the factory (applied at every fresh `Sandbox.create`) or via
+`onSession`'s `use()` (applied via `sandbox.update`):
 
 ```ts
+backend: vercelBackend({ tags: { team: "infra" } });
+// or
 async onSession({ use }) {
   await use({ tags: { team: "infra" } });
 }

package/dist/docs/public/tools.md

@@ -257,9 +257,9 @@ that history bounded:
 
 ### Bound your output inside `execute`
 
-Whatever `execute` returns is exactly what the model sees. Ash does not wrap, re-truncate, or
-re-shape tool results between the executor and the conversation history. If a tool can return
-unbounded text, cap it in the executor before returning:
+Whatever `execute` returns is what the model sees by default. (Use [`toModelOutput`](#tomodeloutput--controlling-what-the-model-sees) to project a
+smaller summary instead.) If a tool can return unbounded text, cap it in the executor before
+returning:
 
 ```ts
 import { defineTool } from "experimental-ash/tools";
@@ -317,6 +317,58 @@ export default defineTool({
 `retentionPolicy` runs every time an older result of this tool exits the protection window. The
 `summary` text replaces the original tool-result output in history.
 
+### `toModelOutput` — Controlling What The Model Sees
+
+By default, the model sees the full return value of `execute`. When a tool returns rich structured
+data that channels need for rendering but the model only needs a summary, use `toModelOutput` to
+project the output:
+
+```ts
+import { defineTool } from "experimental-ash/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description: "Generate a structured account report.",
+  inputSchema: z.object({ domain: z.string() }),
+  async execute({ domain }) {
+    // Full payload — channels see all of this via action.result events.
+    return {
+      domain,
+      opportunityScore: 82,
+      angles: [
+        { title: "API migration", rationale: "3x call growth" },
+        { title: "Dashboard consolidation", rationale: "Multi-product usage" },
+      ],
+      signals: [{ label: "3x API call growth", source: "usage" }],
+    };
+  },
+  // The model only sees a compact summary.
+  toModelOutput(output) {
+    return {
+      type: "text",
+      value: `Report for ${output.domain}: score ${output.opportunityScore}, ${output.angles.length} angles.`,
+    };
+  },
+});
+```
+
+`toModelOutput` receives the full `execute` return (strongly typed) and returns a `ToolModelOutput`:
+
+| Shape                                | When to use                                 |
+| ------------------------------------ | ------------------------------------------- |
+| `{ type: "text", value: string }`    | The model should see a plain text summary.  |
+| `{ type: "json", value: JSONValue }` | The model should see a smaller JSON object. |
+
+When `toModelOutput` is omitted, the model sees the full `execute` return as today.
+
+Channel event handlers and hooks always receive the full `execute` return on `action.result`
+events, regardless of whether `toModelOutput` is defined. This lets channels render rich
+platform-specific output (e.g. Slack Block Kit) from structured tool data that the model never
+needs to see.
+
+Note: `retentionPolicy` and `onCompact` operate on the projected output (what the model sees),
+not the full `execute` return.
+
 ## What To Read Next
 
 - [Session Context](./session-context.md)

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

@@ -79,9 +79,14 @@ Channel and Slack types exported from `experimental-ash/channels/slack`:
   `recentMessages`, `mentionUser`
 - `SlackMessage` - parsed inbound mention or DM payload (`text`, `markdown`, `author`,
   `attachments`, `threadTs`, `channelId`, ...)
+- `loadThreadContextMessages(thread, message, options?)` - refreshes a Slack thread reply and
+  returns recent messages with the triggering message filtered out, or `[]` for thread roots. Pass
+  `since: "last-agent-reply"` to return only messages after the agent's last Slack reply, or
+  `since: (message) => boolean` for a custom boundary.
 - `SlackInteractionAction` - action type for `onInteraction`
 - `SlackMentionResult` / `SlackInboundResult` - return type of `onAppMention` / `onDirectMessage`
-  (`{ auth } | null`)
+  (`{ auth, modelContext? } | null`)
+- `defaultSlackAuth(message, ctx)` - default Slack actor-to-session-auth projection
 - `Card`, `Button`, `Actions`, `Section`, `Modal`, `Table`, etc. - card builders re-exported for
   rendering Slack messages
 

package/dist/src/channel/adapter.js

@@ -13,10 +13,20 @@ const log = createLogger("channel.adapter");
  */
 export function defaultDeliverResult(payload) {
     if (payload.message !== undefined) {
-        return { inputResponses: payload.inputResponses, message: payload.message };
+        return {
+            inputResponses: payload.inputResponses,
+            message: payload.message,
+            modelContext: payload.modelContext,
+        };
     }
     if (payload.inputResponses !== undefined && payload.inputResponses.length > 0) {
-        return { inputResponses: payload.inputResponses };
+        return {
+            inputResponses: payload.inputResponses,
+            modelContext: payload.modelContext,
+        };
+    }
+    if (payload.modelContext !== undefined && payload.modelContext.length > 0) {
+        return { modelContext: payload.modelContext };
     }
     return undefined;
 }

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

@@ -1,4 +1,4 @@
-import type { UserContent } from "ai";
+import type { ModelMessage, UserContent } from "ai";
 import type { CrossChannelReceiveFn } from "#channel/cross-channel-receive.js";
 import type { SessionAuthContext } from "#channel/types.js";
 import type { InputResponse } from "#runtime/input/types.js";
@@ -21,6 +21,14 @@ export interface RouteHandlerArgs<TState = undefined> {
 export interface SendPayload {
     readonly message?: string | UserContent;
     readonly inputResponses?: readonly InputResponse[];
+    /**
+     * Ephemeral messages contributed by the channel, appended to the
+     * dispatched turn's first model call via `StepInput.modelContext`.
+     * Never persisted to durable session history. Use `role: "system"`
+     * for background context that should land before the user message;
+     * other roles land after the user message.
+     */
+    readonly modelContext?: readonly ModelMessage[];
 }
 export type SendFn<TState = undefined> = (input: string | UserContent | SendPayload, options: SendOptions<TState>) => Promise<Session>;
 /**

package/dist/src/channel/send.js

@@ -10,13 +10,13 @@ export function createSendFn(runtime, adapter, channelName) {
         const state = options.state;
         const rawToken = options.continuationToken;
         const continuationToken = `${channelName}:${rawToken}`;
-        const { message: rawMessage, inputResponses } = normalizeSendInput(input);
+        const { message: rawMessage, inputResponses, modelContext } = normalizeSendInput(input);
         const message = serializeUrlFilePartsInMessage(rawMessage);
         try {
             const { sessionId } = await runtime.deliver({
                 auth,
                 continuationToken,
-                payload: { inputResponses, message },
+                payload: { inputResponses, message, modelContext },
             });
             return createSession(sessionId, rawToken, runtime);
         }
@@ -42,7 +42,7 @@ export function createSendFn(runtime, adapter, channelName) {
             auth,
             capabilities: { requestInput: true },
             continuationToken,
-            input: { message: message ?? "" },
+            input: { message: message ?? "", modelContext },
             mode: "conversation",
         });
         return createSession(handle.sessionId, rawToken, runtime);

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

@@ -1,4 +1,4 @@
-import type { UserContent } from "ai";
+import type { ModelMessage, UserContent } from "ai";
 import type { HandleMessageStreamEvent } from "#protocol/message.js";
 import type { RunMode } from "#run-mode.js";
 import type { RuntimeActionResult } from "#runtime/actions/types.js";
@@ -59,6 +59,7 @@ export type EventEmitFn = (event: HandleMessageStreamEvent) => Promise<void>;
 export interface DeliverPayload {
     readonly inputResponses?: readonly InputResponse[];
     readonly message?: string | UserContent;
+    readonly modelContext?: readonly ModelMessage[];
     readonly [key: string]: unknown;
 }
 /**
@@ -177,6 +178,7 @@ export interface RunInput {
     readonly initiatorAuth?: SessionAuthContext | null;
     readonly input: {
         readonly message: string | UserContent;
+        readonly modelContext?: readonly ModelMessage[];
     };
     readonly mode: RunMode;
     readonly parent?: SessionParent;