experimental-ash 0.18.2 → 0.19.0

package/dist/src/public/channels/slack/hitl.js

@@ -11,7 +11,7 @@
  * picks whichever is set so the renderer can pick a widget kind on
  * UX grounds without changing the read path.
  */
-import { truncateModalTitle, truncatePlainText } from "#public/channels/slack/limits.js";
+import { truncateModalTitle, truncatePlainText, truncateSectionText, } from "#public/channels/slack/limits.js";
 /**
  * Wire-format prefix every framework HITL widget mints onto its
  * `action_id`. Exposed so end-user adapters that render their own
@@ -93,7 +93,10 @@ export function isHitlAction(actionId) {
  * Always emits at least the prompt section.
  */
 export function renderInputRequestBlocks(request) {
-    const prompt = { text: { text: request.prompt, type: "mrkdwn" }, type: "section" };
+    const prompt = {
+        text: { text: truncateSectionText(request.prompt), type: "mrkdwn" },
+        type: "section",
+    };
     const actionId = `${HITL_ACTION_PREFIX}${request.requestId}`;
     const options = request.options;
     const acceptsFreeform = request.allowFreeform === true || !options || options.length === 0;
@@ -146,7 +149,7 @@ export function renderInputRequestBlocks(request) {
 export function buildFreeformModalView(input) {
     const title = input.prompt ? truncateModalTitle(input.prompt) : "Your answer";
     const promptBlocks = input.prompt
-        ? [{ type: "section", text: { type: "mrkdwn", text: input.prompt } }]
+        ? [{ type: "section", text: { type: "mrkdwn", text: truncateSectionText(input.prompt) } }]
         : [];
     return {
         type: "modal",

package/dist/src/public/channels/slack/inbound.js

@@ -12,7 +12,7 @@
  *    naming the actor, channel, and thread so the agent's prompt always
  *    knows who and where it is talking.
  */
-import { slackMrkdwnToGfm } from "#public/channels/slack/api.js";
+import { slackMrkdwnToGfm } from "#public/channels/slack/mrkdwn.js";
 /**
  * Parses a Slack `app_mention` event into a {@link SlackMessage}.
  *

package/dist/src/public/channels/slack/index.d.ts

@@ -1,6 +1,9 @@
+export type { ModelMessage } from "ai";
 export { slackChannel, type SlackApiResponse, type SlackBotToken, type SlackChannel, type SlackChannelConfig, type SlackChannelCredentials, type SlackChannelEvents, type SlackChannelState, type SlackContext, type SlackEventContext, type SlackHandle, type SlackInboundResult, type SlackInboundResultOrPromise, type SlackInitialMessage, type SlackInteractionAction, type SlackMentionResult, type SlackMentionResultOrPromise, type SlackReceiveArgs, type SlackThread, type SlackWebhookVerifier, } from "#public/channels/slack/slackChannel.js";
 export type { SlackAttachment, SlackAuthor, SlackInboundContext, SlackMessage, } from "#public/channels/slack/inbound.js";
 export { slackContinuationToken, type SlackPostInput, type SlackPostedMessage, type SlackThreadMessage, type SlackUploadFilesOptions, type SlackUploadFilesResult, } from "#public/channels/slack/api.js";
+export { defaultSlackAuth } from "#public/channels/slack/defaults.js";
+export { loadThreadContextMessages, type LoadThreadContextMessagesOptions, type ThreadContextSince, } from "#public/channels/slack/thread.js";
 export { cardToBlocks, cardToFallbackText, type BlockKitBlock, } from "#public/channels/slack/blocks.js";
 /**
  * Card builders and element types re-exported from the vendored chat

package/dist/src/public/channels/slack/index.js

@@ -1,5 +1,7 @@
 export { slackChannel, } from "#public/channels/slack/slackChannel.js";
 export { slackContinuationToken, } from "#public/channels/slack/api.js";
+export { defaultSlackAuth } from "#public/channels/slack/defaults.js";
+export { loadThreadContextMessages, } from "#public/channels/slack/thread.js";
 export { cardToBlocks, cardToFallbackText, } from "#public/channels/slack/blocks.js";
 /**
  * Card builders and element types re-exported from the vendored chat

package/dist/src/public/channels/slack/limits.d.ts

@@ -20,6 +20,15 @@ export declare const SLACK_TYPING_STATUS_MAX_LENGTH = 50;
  * options and button labels are capped at 75 characters by Slack.
  */
 export declare const SLACK_BLOCK_KIT_PLAIN_TEXT_MAX_LENGTH = 75;
+/**
+ * Block Kit `section` blocks cap `text.text` at 3000 chars. Anything
+ * longer fails the whole post with `invalid_blocks`.
+ */
+export declare const SLACK_SECTION_TEXT_MAX_LENGTH = 3000;
+/**
+ * Top-level `text` field on `chat.postMessage` is capped at 40000 chars.
+ */
+export declare const SLACK_MESSAGE_TEXT_MAX_LENGTH = 40000;
 /**
  * `views.open` modal title is capped at 24 characters.
  */
@@ -37,6 +46,16 @@ export declare function truncateTypingStatus(status: string): string;
  */
 export declare function truncatePlainText(value: string): string;
 export declare function truncatePlainText(value: string | undefined): string | undefined;
+/**
+ * Caps a section block's `text.text` at the Slack limit with a
+ * trailing ellipsis.
+ */
+export declare function truncateSectionText(value: string): string;
+/**
+ * Caps a `chat.postMessage` `text` field at the Slack limit with a
+ * trailing ellipsis.
+ */
+export declare function truncateMessageText(value: string): string;
 /**
  * Caps a modal title at the Slack limit with a trailing ellipsis.
  */

package/dist/src/public/channels/slack/limits.js

@@ -20,6 +20,15 @@ export const SLACK_TYPING_STATUS_MAX_LENGTH = 50;
  * options and button labels are capped at 75 characters by Slack.
  */
 export const SLACK_BLOCK_KIT_PLAIN_TEXT_MAX_LENGTH = 75;
+/**
+ * Block Kit `section` blocks cap `text.text` at 3000 chars. Anything
+ * longer fails the whole post with `invalid_blocks`.
+ */
+export const SLACK_SECTION_TEXT_MAX_LENGTH = 3000;
+/**
+ * Top-level `text` field on `chat.postMessage` is capped at 40000 chars.
+ */
+export const SLACK_MESSAGE_TEXT_MAX_LENGTH = 40000;
 /**
  * `views.open` modal title is capped at 24 characters.
  */
@@ -38,6 +47,20 @@ export function truncatePlainText(value) {
         return undefined;
     return truncateWithEllipsis(value, SLACK_BLOCK_KIT_PLAIN_TEXT_MAX_LENGTH);
 }
+/**
+ * Caps a section block's `text.text` at the Slack limit with a
+ * trailing ellipsis.
+ */
+export function truncateSectionText(value) {
+    return truncateWithEllipsis(value, SLACK_SECTION_TEXT_MAX_LENGTH);
+}
+/**
+ * Caps a `chat.postMessage` `text` field at the Slack limit with a
+ * trailing ellipsis.
+ */
+export function truncateMessageText(value) {
+    return truncateWithEllipsis(value, SLACK_MESSAGE_TEXT_MAX_LENGTH);
+}
 /**
  * Caps a modal title at the Slack limit with a trailing ellipsis.
  */

package/dist/src/public/channels/slack/mrkdwn.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Slack mrkdwn ↔ GitHub-flavored markdown converters and the bare
+ * `@mention` rewriter used by the outbound post pipeline. These are
+ * pure string utilities — no Slack API I/O, no I/O at all — so they
+ * live separately from the binding constructor and request shape code
+ * in {@link ./api.ts}.
+ */
+/**
+ * Rewrites bare `@USER_ID` tokens (the form Slack apps and humans tend
+ * to type) into the `<@USER_ID>` mention syntax Slack actually renders.
+ * Anything already wrapped in `<...>` is left untouched.
+ */
+export declare function rewriteBareMentions(text: string): string;
+/**
+ * Best-effort GFM → Slack mrkdwn converter used only in contexts that
+ * do not support `markdown_text` (e.g. `files.completeUploadExternal`'s
+ * `initial_comment` field).
+ *
+ * The main `{ markdown }` post path sends `markdown_text` directly
+ * to `chat.postMessage` and does not go through this converter.
+ */
+export declare function gfmToSlackMrkdwn(input: string): string;
+/**
+ * Best-effort Slack mrkdwn → GFM converter applied to the text of
+ * every inbound Slack message before the harness sees it.
+ *
+ * - `<@U123>`              → `@U123`
+ * - `<#C123|name>`         → `#name` (or `#C123` when no name)
+ * - `<!channel>` etc.      → `@channel`
+ * - `<https://x|label>`    → `[label](https://x)`
+ * - `<https://x>`          → `https://x`
+ * - `*bold*` (paired)      → `**bold**`
+ * - `~strike~` (paired)    → `~~strike~~`
+ *
+ * Inline `_italic_` and code spans pass through unchanged because both
+ * formats render them identically.
+ */
+export declare function slackMrkdwnToGfm(input: string): string;

package/dist/src/public/channels/slack/mrkdwn.js

@@ -0,0 +1,89 @@
+/**
+ * Slack mrkdwn ↔ GitHub-flavored markdown converters and the bare
+ * `@mention` rewriter used by the outbound post pipeline. These are
+ * pure string utilities — no Slack API I/O, no I/O at all — so they
+ * live separately from the binding constructor and request shape code
+ * in {@link ./api.ts}.
+ */
+const BARE_MENTION_RE = /(?<![<\w])@(\w+)/gu;
+/**
+ * Rewrites bare `@USER_ID` tokens (the form Slack apps and humans tend
+ * to type) into the `<@USER_ID>` mention syntax Slack actually renders.
+ * Anything already wrapped in `<...>` is left untouched.
+ */
+export function rewriteBareMentions(text) {
+    return text.replace(BARE_MENTION_RE, "<@$1>");
+}
+/**
+ * Best-effort GFM → Slack mrkdwn converter used only in contexts that
+ * do not support `markdown_text` (e.g. `files.completeUploadExternal`'s
+ * `initial_comment` field).
+ *
+ * The main `{ markdown }` post path sends `markdown_text` directly
+ * to `chat.postMessage` and does not go through this converter.
+ */
+export function gfmToSlackMrkdwn(input) {
+    const segments = splitCodeFences(input);
+    return segments
+        .map((segment) => (segment.kind === "code" ? segment.text : convertInline(segment.text)))
+        .join("");
+}
+/**
+ * Best-effort Slack mrkdwn → GFM converter applied to the text of
+ * every inbound Slack message before the harness sees it.
+ *
+ * - `<@U123>`              → `@U123`
+ * - `<#C123|name>`         → `#name` (or `#C123` when no name)
+ * - `<!channel>` etc.      → `@channel`
+ * - `<https://x|label>`    → `[label](https://x)`
+ * - `<https://x>`          → `https://x`
+ * - `*bold*` (paired)      → `**bold**`
+ * - `~strike~` (paired)    → `~~strike~~`
+ *
+ * Inline `_italic_` and code spans pass through unchanged because both
+ * formats render them identically.
+ */
+export function slackMrkdwnToGfm(input) {
+    const segments = splitCodeFences(input);
+    return segments
+        .map((segment) => (segment.kind === "code" ? segment.text : decodeInline(segment.text)))
+        .join("");
+}
+function splitCodeFences(input) {
+    const segments = [];
+    const fenceRe = /```[\s\S]*?```|`[^`\n]+`/gu;
+    let lastIndex = 0;
+    for (const match of input.matchAll(fenceRe)) {
+        const start = match.index ?? 0;
+        if (start > lastIndex) {
+            segments.push({ kind: "text", text: input.slice(lastIndex, start) });
+        }
+        segments.push({ kind: "code", text: match[0] });
+        lastIndex = start + match[0].length;
+    }
+    if (lastIndex < input.length) {
+        segments.push({ kind: "text", text: input.slice(lastIndex) });
+    }
+    return segments;
+}
+function convertInline(input) {
+    let out = input;
+    out = out.replace(/\*\*([^*\n]+)\*\*/gu, "*$1*");
+    out = out.replace(/__([^_\n]+)__/gu, "*$1*");
+    out = out.replace(/~~([^~\n]+)~~/gu, "~$1~");
+    out = out.replace(/\[([^\]\n]+)\]\(([^)\s]+)\)/gu, "<$2|$1>");
+    return out;
+}
+function decodeInline(input) {
+    let out = input;
+    out = out.replace(/<!(channel|here|everyone)>/gu, "@$1");
+    out = out.replace(/<@([A-Z0-9]+)\|([^>]+)>/gu, "@$2");
+    out = out.replace(/<@([A-Z0-9]+)>/gu, "@$1");
+    out = out.replace(/<#([A-Z0-9]+)\|([^>]+)>/gu, "#$2");
+    out = out.replace(/<#([A-Z0-9]+)>/gu, "#$1");
+    out = out.replace(/<(https?:\/\/[^|>\s]+)\|([^>]+)>/gu, "[$2]($1)");
+    out = out.replace(/<(https?:\/\/[^>\s]+)>/gu, "$1");
+    out = out.replace(/(^|[^*])\*([^*\n]+)\*(?!\*)/gu, "$1**$2**");
+    out = out.replace(/(^|[^~])~([^~\n]+)~(?!~)/gu, "$1~~$2~~");
+    return out;
+}

package/dist/src/public/channels/slack/slackChannel.d.ts

@@ -1,3 +1,4 @@
+import type { ModelMessage } from "ai";
 import type { TypedReceiveRoute } from "#channel/receive-args.js";
 import type { SessionHandle } from "#channel/session.js";
 import type { SessionAuthContext } from "#channel/types.js";
@@ -158,12 +159,19 @@ export interface SlackInteractionUser {
     readonly name?: string;
 }
 /**
- * Result of an `onAppMention` or `onDirectMessage` callback. Return
- * `{ auth }` (auth may be `null`) to dispatch a turn with that session
- * auth context, or `null` to silently drop the inbound message.
+ * Result of an `onAppMention` or `onDirectMessage` callback. Return an
+ * object (auth may be `null`) to dispatch a turn, or `null` to silently
+ * drop the inbound message.
+ *
+ * `modelContext` mirrors lifecycle hook results: it contributes
+ * ephemeral messages to the next model call only, without writing them
+ * to durable session history. Use `role: "system"` for Slack thread
+ * background context so it lands before the user's mention; see
+ * `docs/public/channels/slack.md`.
  */
 export type SlackMentionResult = {
-    auth: SessionAuthContext | null;
+    readonly auth: SessionAuthContext | null;
+    readonly modelContext?: readonly ModelMessage[];
 } | null;
 export type SlackMentionResultOrPromise = SlackMentionResult | Promise<SlackMentionResult>;
 /**

package/dist/src/public/channels/slack/slackChannel.js

@@ -14,13 +14,7 @@ function rebuildSlackContext(state, session, credentials) {
         channelId: state.channelId ?? "",
         threadTs: state.threadTs ?? "",
         teamId: state.teamId ?? undefined,
-        // First `ctx.thread.post(...)` in a session that started without a
-        // thread (programmatic start, schedule firing, etc.) becomes the
-        // thread root. We update durable adapter state so subsequent
-        // posts thread under it, and re-key the parked session so a
-        // follow-up `@mention` reply in the same thread resumes the same
-        // workflow.
-        onAnchor(ts) {
+        onThreadTsChanged(ts) {
             state.threadTs = ts;
             if (state.channelId) {
                 session.setContinuationToken(slackContinuationToken(state.channelId, ts));
@@ -236,7 +230,10 @@ async function dispatchInboundMessage(input) {
         ? prependSlackContext(baseMessage, inboundContext)
         : baseMessage;
     try {
-        await input.send(turnMessage, {
+        await input.send({
+            message: turnMessage,
+            modelContext: result.modelContext,
+        }, {
             auth: result.auth,
             continuationToken: slackContinuationToken(message.channelId, message.threadTs),
             state: {

package/dist/src/public/channels/slack/thread.d.ts

@@ -0,0 +1,26 @@
+import type { SlackThread, SlackThreadMessage } from "#public/channels/slack/api.js";
+export type ThreadContextSince = "thread-root" | "last-agent-reply" | ((message: SlackThreadMessage) => boolean);
+export interface LoadThreadContextMessagesOptions {
+    /**
+     * Boundary for returned context messages. Defaults to `"thread-root"`.
+     *
+     * Use `"last-agent-reply"` to include only user/thread messages
+     * since the last agent-authored Slack reply. Pass a predicate
+     * function for custom boundaries, such as "since the last message
+     * that mentioned a particular user".
+     */
+    readonly since?: ThreadContextSince;
+}
+/**
+ * Loads messages that are useful as background context for the current
+ * Slack thread turn.
+ *
+ * Returns an empty array when `message` is the thread root. For thread
+ * replies, refreshes the bound Slack thread and returns its recent
+ * messages before the triggering message, filtered by {@link options}.
+ * Formatting and model-message role choice stay with the caller.
+ */
+export declare function loadThreadContextMessages(thread: Pick<SlackThread, "recentMessages" | "refresh">, message: {
+    readonly threadTs: string;
+    readonly ts: string;
+}, options?: LoadThreadContextMessagesOptions): Promise<SlackThreadMessage[]>;

package/dist/src/public/channels/slack/thread.js

@@ -0,0 +1,45 @@
+/**
+ * Loads messages that are useful as background context for the current
+ * Slack thread turn.
+ *
+ * Returns an empty array when `message` is the thread root. For thread
+ * replies, refreshes the bound Slack thread and returns its recent
+ * messages before the triggering message, filtered by {@link options}.
+ * Formatting and model-message role choice stay with the caller.
+ */
+export async function loadThreadContextMessages(thread, message, options = {}) {
+    if (isThreadRootMessage(message)) {
+        return [];
+    }
+    await thread.refresh();
+    const currentIndex = thread.recentMessages.findIndex((entry) => entry.ts === message.ts);
+    const candidateMessages = currentIndex === -1 ? thread.recentMessages : thread.recentMessages.slice(0, currentIndex);
+    const priorMessages = candidateMessages.filter((entry) => entry.threadTs === message.threadTs && entry.ts !== message.ts);
+    return applySinceBoundary(priorMessages, options.since);
+}
+function isThreadRootMessage(message) {
+    return message.threadTs === message.ts;
+}
+function findLastIndex(items, predicate) {
+    for (let index = items.length - 1; index >= 0; index -= 1) {
+        if (predicate(items[index])) {
+            return index;
+        }
+    }
+    return -1;
+}
+function applySinceBoundary(messages, since) {
+    const boundary = since ?? "thread-root";
+    if (typeof boundary === "function") {
+        const lastMatchingIndex = findLastIndex(messages, boundary);
+        return messages.slice(lastMatchingIndex + 1);
+    }
+    switch (boundary) {
+        case "thread-root":
+            return [...messages];
+        case "last-agent-reply": {
+            const lastAgentReplyIndex = findLastIndex(messages, (entry) => entry.isMe);
+            return messages.slice(lastAgentReplyIndex + 1);
+        }
+    }
+}

package/dist/src/public/definitions/defineChannel.d.ts

@@ -37,7 +37,7 @@ export interface ChannelConfig<TState = undefined, TCtx = void> {
      * Builds the per-step channel context handed to `events` and
      * `deliver`. Receives the live {@link SessionHandle} so factories
      * that need to wire late-bound callbacks (e.g. Slack's auto-anchor
-     * `onAnchor` calling `session.setContinuationToken(...)`) can close
+     * `onThreadTsChanged` calling `session.setContinuationToken(...)`) can close
      * over it. State mutations made inside the returned context flow
      * back through `adapter.state` automatically.
      */

package/dist/src/public/sandbox/backends/default.d.ts

@@ -1,7 +1,22 @@
 import type { SandboxBackend } from "#public/definitions/sandbox-backend.js";
+import type { LocalSandboxCreateOptions } from "#public/sandbox/local-sandbox.js";
+import type { VercelSandboxCreateOptions } from "#public/sandbox/vercel-sandbox.js";
+/**
+ * Input to {@link defaultBackend}: a separate options bag per inner
+ * backend. The framework picks one bag at runtime based on `process.env.VERCEL`
+ * and passes it to the chosen factory; the other is ignored.
+ */
+export interface DefaultBackendOptions {
+    readonly local?: LocalSandboxCreateOptions;
+    readonly vercel?: VercelSandboxCreateOptions;
+}
 /**
  * Constructs an env-aware sandbox backend that delegates to
  * {@link vercelBackend} on hosted Vercel (where `process.env.VERCEL`
  * is truthy) and to {@link localBackend} everywhere else.
+ *
+ * Optionally accepts a keyed options bag (`{ local, vercel }`) so each
+ * inner backend receives its own typed create options without forcing
+ * authors to pin to one backend up front.
  */
-export declare function defaultBackend(): SandboxBackend;
+export declare function defaultBackend(opts?: DefaultBackendOptions): SandboxBackend;

package/dist/src/public/sandbox/backends/default.js

@@ -1,27 +1,15 @@
+import { lazyBackend } from "#execution/sandbox/lazy-backend.js";
 import { localBackend } from "#public/sandbox/backends/local.js";
 import { vercelBackend } from "#public/sandbox/backends/vercel.js";
 /**
  * Constructs an env-aware sandbox backend that delegates to
  * {@link vercelBackend} on hosted Vercel (where `process.env.VERCEL`
  * is truthy) and to {@link localBackend} everywhere else.
+ *
+ * Optionally accepts a keyed options bag (`{ local, vercel }`) so each
+ * inner backend receives its own typed create options without forcing
+ * authors to pin to one backend up front.
  */
-export function defaultBackend() {
-    let resolved;
-    function resolve() {
-        if (resolved === undefined) {
-            resolved = process.env.VERCEL ? vercelBackend() : localBackend();
-        }
-        return resolved;
-    }
-    return {
-        get name() {
-            return resolve().name;
-        },
-        create(input) {
-            return resolve().create(input);
-        },
-        async prewarm(input) {
-            await resolve().prewarm(input);
-        },
-    };
+export function defaultBackend(opts) {
+    return lazyBackend(() => process.env.VERCEL ? vercelBackend(opts?.vercel) : localBackend(opts?.local));
 }

package/dist/src/public/sandbox/backends/local.d.ts

@@ -1,4 +1,5 @@
 import type { SandboxBackend } from "#public/definitions/sandbox-backend.js";
+import type { LocalSandboxCreateOptions } from "#public/sandbox/local-sandbox.js";
 /**
  * Constructs the built-in local sandbox backend.
  *
@@ -7,8 +8,10 @@ import type { SandboxBackend } from "#public/definitions/sandbox-backend.js";
  * under the application root. It is the default backend on developer
  * machines (`pnpm ash dev`).
  *
- * Takes no arguments today — `just-bash` does not currently expose any
- * configuration that's worth surfacing through ash. New options would
- * be added here as the underlying runtime grows.
+ * Accepts an `opts` parameter for parity with other backends, but
+ * `LocalSandboxCreateOptions` is empty today — `just-bash` does not
+ * currently expose any configuration worth surfacing. New options would
+ * be added by widening `LocalSandboxCreateOptions` and routing them
+ * into the binding without changing this signature.
  */
-export declare function localBackend(): SandboxBackend;
+export declare function localBackend(opts?: LocalSandboxCreateOptions): SandboxBackend;

package/dist/src/public/sandbox/backends/local.js

@@ -7,10 +7,12 @@ import { createLocalSandboxBackend } from "#execution/sandbox/bindings/local.js"
  * under the application root. It is the default backend on developer
  * machines (`pnpm ash dev`).
  *
- * Takes no arguments today — `just-bash` does not currently expose any
- * configuration that's worth surfacing through ash. New options would
- * be added here as the underlying runtime grows.
+ * Accepts an `opts` parameter for parity with other backends, but
+ * `LocalSandboxCreateOptions` is empty today — `just-bash` does not
+ * currently expose any configuration worth surfacing. New options would
+ * be added by widening `LocalSandboxCreateOptions` and routing them
+ * into the binding without changing this signature.
  */
-export function localBackend() {
-    return createLocalSandboxBackend();
+export function localBackend(opts) {
+    return createLocalSandboxBackend({ createOptions: opts });
 }

package/dist/src/public/sandbox/backends/vercel.d.ts

@@ -1,11 +1,17 @@
 import type { SandboxBackend } from "#public/definitions/sandbox-backend.js";
-import type { VercelSandboxBootstrapUseOptions, VercelSandboxSessionUseOptions } from "#public/sandbox/vercel-sandbox.js";
+import type { VercelSandboxBootstrapUseOptions, VercelSandboxCreateOptions, VercelSandboxSessionUseOptions } from "#public/sandbox/vercel-sandbox.js";
 /**
  * Constructs the built-in Vercel sandbox backend.
  *
+ * The optional `opts` parameter is forwarded to the Vercel SDK's
+ * `Sandbox.create(...)` for every fresh sandbox the framework creates
+ * (template at prewarm, session at first-time create). On resume
+ * (`Sandbox.get`), no create happens, so opts are not re-applied.
+ *
  * `bootstrap({ use })` applies its options to the template via
  * `sandbox.update(...)`; those settings persist into the snapshot.
  * `onSession({ use })` applies its options to the live session via the
- * SDK's `update` under the hood.
+ * SDK's `update` under the hood — overriding any overlapping field
+ * from `opts`.
  */
-export declare function vercelBackend(): SandboxBackend<VercelSandboxBootstrapUseOptions, VercelSandboxSessionUseOptions>;
+export declare function vercelBackend(opts?: VercelSandboxCreateOptions): SandboxBackend<VercelSandboxBootstrapUseOptions, VercelSandboxSessionUseOptions>;

package/dist/src/public/sandbox/backends/vercel.js

@@ -2,11 +2,17 @@ import { createVercelSandboxBackend } from "#execution/sandbox/bindings/vercel.j
 /**
  * Constructs the built-in Vercel sandbox backend.
  *
+ * The optional `opts` parameter is forwarded to the Vercel SDK's
+ * `Sandbox.create(...)` for every fresh sandbox the framework creates
+ * (template at prewarm, session at first-time create). On resume
+ * (`Sandbox.get`), no create happens, so opts are not re-applied.
+ *
  * `bootstrap({ use })` applies its options to the template via
  * `sandbox.update(...)`; those settings persist into the snapshot.
  * `onSession({ use })` applies its options to the live session via the
- * SDK's `update` under the hood.
+ * SDK's `update` under the hood — overriding any overlapping field
+ * from `opts`.
  */
-export function vercelBackend() {
-    return createVercelSandboxBackend();
+export function vercelBackend(opts) {
+    return createVercelSandboxBackend({ createOptions: opts });
 }

package/dist/src/public/sandbox/index.d.ts

@@ -9,4 +9,5 @@ export { SandboxTemplateNotProvisionedError } from "#public/definitions/sandbox-
 export { defaultBackend } from "#public/sandbox/backends/default.js";
 export { localBackend } from "#public/sandbox/backends/local.js";
 export { vercelBackend } from "#public/sandbox/backends/vercel.js";
-export type { VercelSandboxBootstrapUseOptions, VercelSandboxSessionUseOptions, } from "#public/sandbox/vercel-sandbox.js";
+export type { LocalSandboxCreateOptions } from "#public/sandbox/local-sandbox.js";
+export type { VercelSandboxBootstrapUseOptions, VercelSandboxCreateOptions, VercelSandboxSessionUseOptions, } from "#public/sandbox/vercel-sandbox.js";

package/dist/src/public/sandbox/local-sandbox.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Options accepted by `localBackend(opts)`. Reserved for future
+ * widening: today the local backend exposes no consumer-controllable
+ * create options, so this is an empty object. The parameter exists on
+ * the factory so adding real fields here later is purely additive.
+ */
+export type LocalSandboxCreateOptions = Record<string, never>;

package/dist/src/public/sandbox/local-sandbox.js

@@ -0,0 +1 @@
+export {};

package/dist/src/public/sandbox/vercel-sandbox.d.ts

@@ -1,4 +1,16 @@
-import type { SandboxUpdateParams } from "#compiled/@vercel/sandbox/index.js";
+import type { Sandbox as SdkSandbox, SandboxUpdateParams } from "#compiled/@vercel/sandbox/index.js";
+/**
+ * Options accepted by `vercelBackend(opts)`. Forwarded directly to the
+ * Vercel SDK's `Sandbox.create(...)` for every fresh sandbox the
+ * framework creates (template at prewarm time, session at first-time
+ * session-create). Skipped on resume (`Sandbox.get`) since no create
+ * happens there.
+ *
+ * Framework-injected fields (`name`, `persistent`, `source`, `signal`)
+ * are excluded — the framework owns those and overrides any author-
+ * supplied values.
+ */
+export type VercelSandboxCreateOptions = Omit<NonNullable<Parameters<typeof SdkSandbox.create>[0]>, "name" | "persistent" | "source" | "signal">;
 /**
  * Options accepted by the Vercel backend's `bootstrap({ use })` hook.
  * Aliases the Vercel SDK's `SandboxUpdateParams` because bootstrap

package/dist/src/runtime/resolve-sandbox.js

@@ -1,3 +1,4 @@
+import { lazyBackend } from "#execution/sandbox/lazy-backend.js";
 import { expectObjectRecord } from "#internal/authored-module.js";
 import { defaultBackend } from "#public/sandbox/backends/default.js";
 import { toErrorMessage } from "#shared/errors.js";
@@ -47,8 +48,11 @@ function resolveBackend(value, logicalPath) {
     if (value === undefined) {
         return defaultBackend();
     }
+    if (typeof value === "function") {
+        return lazyBackend(value);
+    }
     if (typeof value !== "object" || value === null) {
-        throw new ResolveAgentError(`Sandbox "${logicalPath}" exposed a non-object "backend" field. Use vercelBackend(), localBackend(), or another factory that returns a SandboxBackend value.`, { logicalPath });
+        throw new ResolveAgentError(`Sandbox "${logicalPath}" exposed a non-object "backend" field. Use vercelBackend(), localBackend(), another factory that returns a SandboxBackend value, or a zero-arg callback returning one.`, { logicalPath });
     }
     const record = value;
     if (typeof record.name !== "string" || record.name.length === 0) {

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

@@ -15,6 +15,7 @@ import type { SourceRef, ModuleSourceRef, SkillPackageSourceRef, MarkdownSourceR
 import type { InternalSkillDefinition } from "#shared/skill-definition.js";
 import type { InternalAgentDefinition } from "#shared/agent-definition.js";
 import type { InternalToolDefinitionWithExecuteFn } from "#shared/tool-definition.js";
+import type { SandboxBackend } from "#shared/sandbox-backend.js";
 import type { SandboxDefinition } from "#shared/sandbox-definition.js";
 /**
  * Runtime-owned source ref describing one additive config module import.
@@ -82,7 +83,15 @@ export interface ResolvedConnectionDefinition extends ResolvedModuleSourceRef {
  * `vercelBackend()` and `localBackend()` based on the current
  * environment).
  */
-export type ResolvedSandboxDefinition = Readonly<SandboxDefinition> & ResolvedModuleSourceRef & {
+export type ResolvedSandboxDefinition = Readonly<Omit<SandboxDefinition, "backend">> & ResolvedModuleSourceRef & {
+    /**
+     * Resolved backend value. The authored `SandboxDefinition.backend`
+     * accepts either a `SandboxBackend` or a `() => SandboxBackend`; by
+     * the time it reaches the runtime the function form has been
+     * unwrapped via `lazyBackend(...)` so consumers always see a plain
+     * value.
+     */
+    readonly backend: SandboxBackend;
     readonly description?: string;
 };
 /**