experimental-ash 0.18.3 → 0.20.0

package/dist/src/internal/workflow-bundle/builder.js

@@ -4,7 +4,7 @@ import { dirname, join, relative, resolve } from "node:path";
 import { resolvePackageSourceDirectoryPath, resolveWorkflowModulePath, } from "#internal/application/package.js";
 import { prepareAshVersionedCacheDirectory, writeAshVersionedCacheMetadata, } from "#internal/application/cache-metadata.js";
 import { normalizeEsmImportSpecifier } from "#internal/application/import-specifier.js";
-import { bundleFinalWorkflowOutput, collectWorkflowInputFiles, convertClassesManifest, convertStepsManifest, convertWorkflowsManifest, createAshPackageImportsPlugin, createWorkflowImport, createWorkflowPseudoPackagePlugin, createWorkflowTransformPlugin, createWorkflowVirtualEntryPlugin, WORKFLOW_VIRTUAL_ENTRY_ID, } from "#internal/workflow-bundle/builder-support.js";
+import { atomicWriteFile, bundleFinalWorkflowOutput, collectWorkflowInputFiles, convertClassesManifest, convertStepsManifest, convertWorkflowsManifest, createAshPackageImportsPlugin, createWorkflowImport, createWorkflowPseudoPackagePlugin, createWorkflowTransformPlugin, createWorkflowVirtualEntryPlugin, WORKFLOW_VIRTUAL_ENTRY_ID, } from "#internal/workflow-bundle/builder-support.js";
 import { buildWithNitroRolldown, getSingleRolldownChunk, } from "#internal/bundler/nitro-rolldown.js";
 import { writeNitroStepEntrypoint } from "#internal/workflow-bundle/nitro-step-entry.js";
 import { copyNitroFunctionDirectory, createWorkflowFunctionEnvironment, retargetNitroFunctionDirectoryToWorkflowRoute, WORKFLOW_BUILDER_DEFERRED_PACKAGES, WORKFLOW_STEP_EXTERNAL_PACKAGES, } from "#internal/workflow-bundle/vercel-workflow-output.js";
@@ -347,12 +347,12 @@ async function addStepRegistrationsImport(workflowBundlePath, stepRegistrationsP
     ].join("\n");
     const firstImportMatch = source.match(/^import\s.+?;\n/m);
     if (firstImportMatch === null || firstImportMatch.index === undefined) {
-        await writeFile(workflowBundlePath, `${importSource}${source}`);
+        await atomicWriteFile(workflowBundlePath, `${importSource}${source}`);
         return;
     }
     const insertionIndex = firstImportMatch.index + firstImportMatch[0].length;
     const nextSource = `${source.slice(0, insertionIndex)}${importSource}${source.slice(insertionIndex)}`;
-    await writeFile(workflowBundlePath, nextSource);
+    await atomicWriteFile(workflowBundlePath, nextSource);
 }
 async function rewriteWorkflowRuntimeImports(filePath) {
     const source = await readTextFileIfPresent(filePath);
@@ -371,7 +371,7 @@ async function rewriteWorkflowRuntimeImports(filePath) {
         nextSource = replaceStringLiteralSpecifier(nextSource, specifier, resolvedSpecifier);
     }
     if (nextSource !== source) {
-        await writeFile(filePath, nextSource);
+        await atomicWriteFile(filePath, nextSource);
     }
 }
 async function rewriteWorkflowCodeLiteral(filePath) {
@@ -394,7 +394,7 @@ async function rewriteWorkflowCodeLiteral(filePath) {
     const workflowCode = decodeWorkflowCodeTemplateLiteral(expression, filePath);
     const nextSource = `${source.slice(0, valueStart)}${encodeWorkflowCodeLiteral(workflowCode)}${source.slice(expressionEnd)}`;
     if (nextSource !== source) {
-        await writeFile(filePath, nextSource);
+        await atomicWriteFile(filePath, nextSource);
     }
 }
 function encodeWorkflowCodeLiteral(workflowCode) {
@@ -468,5 +468,5 @@ async function mirrorFileBypassingUnlink(sourcePath, targetPath) {
     if (existingContents !== null && existingContents.equals(sourceContents)) {
         return;
     }
-    await writeFile(targetPath, sourceContents);
+    await atomicWriteFile(targetPath, sourceContents);
 }

package/dist/src/public/channels/slack/api-encoding.d.ts

@@ -1,4 +1,4 @@
-export declare function encodeSlackApiBody(body: unknown, encoding: "form" | "json"): {
+export declare function encodeSlackApiBody(body: unknown): {
     readonly body: string;
     readonly contentType: string;
 };

package/dist/src/public/channels/slack/api-encoding.js

@@ -1,10 +1,4 @@
-export function encodeSlackApiBody(body, encoding) {
-    if (encoding === "json") {
-        return {
-            body: JSON.stringify(body),
-            contentType: "application/json; charset=utf-8",
-        };
-    }
+export function encodeSlackApiBody(body) {
     const params = new URLSearchParams();
     if (body && typeof body === "object") {
         for (const [key, value] of Object.entries(body)) {

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

@@ -42,15 +42,16 @@ export interface SlackApiResponse {
 /**
  * Low-level POST to a Slack Web API method.
  *
- * Signs the request with the bot token. Returns Slack's raw JSON
- * response — callers are expected to inspect `response.ok` themselves
- * when they care about success/failure semantics.
+ * Signs with the bot token and form-encodes the body — Slack documents
+ * `application/x-www-form-urlencoded` as universal, JSON support is
+ * partial (e.g. `conversations.replies` rejects JSON), so form is the
+ * only safe default. Returns Slack's raw JSON response; callers inspect
+ * `response.ok` themselves.
  */
 export declare function callSlackApi(input: {
     readonly botToken: SlackBotToken | undefined;
     readonly operation: string;
     readonly body: unknown;
-    readonly encoding?: "form" | "json";
 }): Promise<SlackApiResponse>;
 /**
  * Builds the `request(op, body)` Slack API caller installed on every

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

@@ -43,13 +43,15 @@ export async function resolveSlackBotToken(token) {
 /**
  * Low-level POST to a Slack Web API method.
  *
- * Signs the request with the bot token. Returns Slack's raw JSON
- * response — callers are expected to inspect `response.ok` themselves
- * when they care about success/failure semantics.
+ * Signs with the bot token and form-encodes the body — Slack documents
+ * `application/x-www-form-urlencoded` as universal, JSON support is
+ * partial (e.g. `conversations.replies` rejects JSON), so form is the
+ * only safe default. Returns Slack's raw JSON response; callers inspect
+ * `response.ok` themselves.
  */
 export async function callSlackApi(input) {
     const token = await resolveSlackBotToken(input.botToken);
-    const encoded = encodeSlackApiBody(input.body, input.encoding ?? "json");
+    const encoded = encodeSlackApiBody(input.body);
     const response = await fetch(`https://slack.com/api/${input.operation}`, {
         method: "POST",
         headers: {
@@ -99,7 +101,6 @@ export function buildSlackBinding(input) {
             const getUrl = await callSlackApi({
                 botToken: input.botToken,
                 operation: "files.getUploadURLExternal",
-                encoding: "form",
                 body: {
                     filename: file.filename,
                     length: bytes.byteLength,
@@ -135,7 +136,6 @@ export function buildSlackBinding(input) {
         const complete = await callSlackApi({
             botToken: input.botToken,
             operation: "files.completeUploadExternal",
-            encoding: "form",
             body: completeBody,
         });
         if (complete.ok !== true) {

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/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

@@ -230,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/sandbox.d.ts

@@ -1,6 +1,6 @@
 import type { Optional } from "#shared/optional.js";
 import type { SandboxDefinition as SharedSandboxDefinition } from "#shared/sandbox-definition.js";
-export type { SandboxCommandOptions, SandboxCommandResult, SandboxReadTextFileOptions, SandboxSession, SandboxWriteTextFileOptions, } from "#shared/sandbox-session.js";
+export type { SandboxCommandResult, SandboxReadBinaryFileOptions, SandboxReadFileOptions, SandboxReadTextFileOptions, SandboxRunCommandOptions, SandboxSession, SandboxWriteBinaryFileOptions, SandboxWriteFileOptions, SandboxWriteTextFileOptions, } from "#shared/sandbox-session.js";
 export type { SandboxBootstrapUseFn, SandboxSessionUseFn, SandboxBootstrapContext, SandboxSessionContext, } from "#shared/sandbox-definition.js";
 export type SandboxDefinition<BO = Record<string, never>, SO = Record<string, never>> = Optional<SharedSandboxDefinition<BO, SO>, "backend">;
 /**

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

@@ -47,6 +47,19 @@ export interface NeedsApprovalContext {
  * function. These are the same options the SDK passes to every tool call.
  */
 export type ToolExecuteOptions = Readonly<AiSdkToolExecuteOptions>;
+/**
+ * Ash-owned shape for the model-facing tool result produced by
+ * {@link ToolDefinition.toModelOutput}. Structurally compatible with the
+ * AI SDK's `ToolResultOutput` so the harness can forward it without
+ * conversion.
+ */
+export type ToolModelOutput = {
+    readonly type: "text";
+    readonly value: string;
+} | {
+    readonly type: "json";
+    readonly value: unknown;
+};
 /**
  * Result returned from a {@link ToolRetentionPolicy} function.
  *
@@ -106,6 +119,17 @@ export type ToolDefinition<TInput = unknown, TOutput = unknown> = PublicToolDefi
      * {@link ToolRetentionPolicy}.
      */
     retentionPolicy?: ToolRetentionPolicy<TOutput>;
+    /**
+     * Optional projection that controls what the model sees as the tool
+     * result. Receives the full `TOutput` from {@link execute} and returns
+     * a {@link ToolModelOutput} that becomes the model-facing tool result.
+     *
+     * When omitted, the model sees the full `execute` return value
+     * (default AI SDK serialization). Channel event handlers
+     * (`action.result`) always receive the full output regardless of
+     * whether this function is defined.
+     */
+    toModelOutput?: (output: TOutput) => ToolModelOutput | Promise<ToolModelOutput>;
     /**
      * Called after message-history compaction. The framework invokes this
      * hook for every tool that declares it, in tool registration order,
@@ -125,6 +149,7 @@ export declare function defineTool<TSchema extends StandardJSONSchemaV1<unknown,
     execute: ToolDefinition<StandardJSONSchemaV1.InferOutput<TSchema>, TOutput>["execute"];
     needsApproval?: ToolDefinition<unknown, unknown>["needsApproval"];
     retentionPolicy?: ToolDefinition<unknown, TOutput>["retentionPolicy"];
+    toModelOutput?: ToolDefinition<unknown, TOutput>["toModelOutput"];
     onCompact?: ToolDefinition<unknown, unknown>["onCompact"];
 }): ToolDefinition<StandardJSONSchemaV1.InferOutput<TSchema>, TOutput>;
 export declare function defineTool<TInput = unknown, TOutput = unknown>(definition: ToolDefinition<TInput, TOutput>): ToolDefinition<TInput, TOutput>;

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

@@ -3,10 +3,11 @@
  * `agent/sandbox/sandbox.ts` when paired with a `workspace/` folder).
  */
 export { getSandbox } from "#context/accessors.js";
-export { defineSandbox, type SandboxBootstrapContext, type SandboxBootstrapUseFn, type SandboxCommandOptions, type SandboxCommandResult, type SandboxDefinition, type SandboxReadTextFileOptions, type SandboxSession, type SandboxSessionContext, type SandboxSessionUseFn, type SandboxWriteTextFileOptions, } from "#public/definitions/sandbox.js";
+export { defineSandbox, type SandboxBootstrapContext, type SandboxBootstrapUseFn, type SandboxCommandResult, type SandboxDefinition, type SandboxReadBinaryFileOptions, type SandboxReadFileOptions, type SandboxReadTextFileOptions, type SandboxRunCommandOptions, type SandboxSession, type SandboxSessionContext, type SandboxSessionUseFn, type SandboxWriteBinaryFileOptions, type SandboxWriteFileOptions, type SandboxWriteTextFileOptions, } from "#public/definitions/sandbox.js";
 export type { SandboxBackend, SandboxBackendCreateInput, SandboxBackendHandle, SandboxBackendPrewarmInput, SandboxBackendRuntimeContext, SandboxBackendSessionState, SandboxSeedFile, } from "#public/definitions/sandbox-backend.js";
 export { SandboxTemplateNotProvisionedError } from "#public/definitions/sandbox-backend.js";
 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/public/tools/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * Tool authoring helpers for `agent/tools/*.ts` files.
  */
-export { type CompactionHookInput, type CompactionHookResult, type DisabledToolSentinel, defineTool, disableTool, isDisabledToolSentinel, type NeedsApprovalContext, type RetentionSummary, type ToolDefinition, type ToolRetentionPolicy, } from "#public/definitions/tool.js";
+export { type CompactionHookInput, type CompactionHookResult, type DisabledToolSentinel, defineTool, disableTool, isDisabledToolSentinel, type NeedsApprovalContext, type RetentionSummary, type ToolDefinition, type ToolModelOutput, type ToolRetentionPolicy, } from "#public/definitions/tool.js";
 export { type DefineBashToolInput, defineBashTool } from "#public/tools/define-bash-tool.js";
 export { type DefineGlobToolInput, defineGlobTool } from "#public/tools/define-glob-tool.js";
 export { type DefineGrepToolInput, defineGrepTool } from "#public/tools/define-grep-tool.js";

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/resolve-tool.js

@@ -60,6 +60,9 @@ function extractOptionalHooks(record, definition) {
     if (retentionPolicy !== undefined) {
         optional.retentionPolicy = retentionPolicy;
     }
+    if (record.toModelOutput !== undefined) {
+        optional.toModelOutput = expectFunction(record.toModelOutput, describe(definition, "to provide a toModelOutput function"));
+    }
     if (record.inputSchema !== undefined && isFlexibleSchema(record.inputSchema)) {
         optional.inputStandardSchema = record.inputSchema;
     }

package/dist/src/runtime/skills/sandbox-access.js

@@ -27,7 +27,7 @@ export async function loadSkillFromSandbox(access, id) {
     assertSafeSkillId(id);
     const sandbox = await requireSandboxSession(access);
     const path = skillFilePath(id, "SKILL.md");
-    const instructions = await sandbox.readTextFile(path);
+    const instructions = await sandbox.readTextFile({ path });
     if (instructions === null) {
         throw new Error(`No skill named "${id}" at ${path}.`);
     }
@@ -47,14 +47,14 @@ export function createSandboxSkillHandle(access, id) {
             return {
                 async bytes() {
                     const sandbox = await requireSandboxSession(access);
-                    const content = await sandbox.readBinaryFile(path);
+                    const content = await sandbox.readBinaryFile({ path });
                     if (content === null)
                         throw new Error(`Skill file not found: ${path}`);
                     return content;
                 },
                 async text() {
                     const sandbox = await requireSandboxSession(access);
-                    const content = await sandbox.readTextFile(path);
+                    const content = await sandbox.readTextFile({ path });
                     if (content === null)
                         throw new Error(`Skill file not found: ${path}`);
                     return content;

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

@@ -5,7 +5,7 @@ import type { DiscoverDiagnosticsSummary } from "#discover/diagnostics.js";
 import type { ChannelMethod, RouteContext } from "#public/definitions/channel.js";
 import type { RouteHandler } from "#channel/routes.js";
 import type { LifecycleHooks, StreamEventHook } from "#public/definitions/hook.js";
-import type { CompactionHookInput, CompactionHookResult, NeedsApprovalContext, ToolRetentionPolicy } from "#public/definitions/tool.js";
+import type { CompactionHookInput, CompactionHookResult, NeedsApprovalContext, ToolModelOutput, ToolRetentionPolicy } from "#public/definitions/tool.js";
 import type { AuthorizationDefinition, HeadersDefinition, ToolFilterDefinition } from "#runtime/connections/types.js";
 import type { CompiledWorkspaceResourceRoot } from "#compiler/manifest.js";
 import type { WorkspaceRuntimeSpec } from "#runtime/workspace/types.js";
@@ -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;
 };
 /**
@@ -127,6 +136,12 @@ export type ResolvedToolDefinition = Readonly<Optional<InternalToolDefinitionWit
      * history. See `packages/ash/src/execution/tool-compaction.ts`.
      */
     readonly onCompact?: (input: CompactionHookInput) => CompactionHookResult | Promise<CompactionHookResult> | void | Promise<void>;
+    /**
+     * Optional projection that controls what the model sees as the tool
+     * result. The full `execute` return is still visible to channel event
+     * handlers and the stream. See {@link ToolModelOutput}.
+     */
+    readonly toModelOutput?: (output: unknown) => ToolModelOutput | Promise<ToolModelOutput>;
 };
 /**
  * Runtime-owned authored hook definition resolved from a compiled module