experimental-ash 0.58.0 → 0.59.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # experimental-ash
 
+## 0.59.0
+
+### Minor Changes
+
+- c0f795d: Unify code mode's host-interrupt handling and remove Ash's per-callback context shims. `experimental-ai-sdk-code-mode` now re-enters the originating invocation's async context at the worker bridge for every host callback, so the code-mode host-tool wrapper and lifecycle projection are context-transparent (no more pinning `execute`, `needsApproval`, or `emit` to a build-time context). Nested-tool approval and connection auth now ride one generic `CodeModeInterrupt` park/resume path instead of two bespoke ones, so any durable interrupt kind resumes through a single seam.
+- 77aeeee: Add per-tool authorization. `defineTool` now accepts an `auth` field (the same shapes as connection auth: `connect("...")`, a custom interactive definition, or `{ getToken }`), and the tool's `execute` context gains `ctx.getToken()` and `ctx.requireAuth()`. A token cache miss or a thrown `ConnectionAuthorizationRequiredError` suspends the turn, drives the OAuth consent flow on a tool-scoped callback URL, and re-runs the tool after the user authorizes.
+
+### Patch Changes
+
+- 651b295: Constrain the Next.js dev-server origin parser to loopback URLs so dependency metadata URLs cannot be written to the Ash dev-server registry.
+- c0f795d: Project code-mode nested tool results through the same Ash-owned `action.result` helper as native tool calls. The code-mode lifecycle no longer uses a separate strict-JSON coercion with an error fallback; both paths now funnel through one `createRuntimeToolResultFromValue` helper, so the raw-output (never `toModelOutput`) decision is made once and code-mode nested results carry their raw structured output exactly like native results.
+- b932acd: Fix the dev TUI mangling URLs that contain underscores. The terminal markdown renderer treated `_…_` as italics and stripped the underscores, corrupting Vercel Connect authorization URLs (`sca_…`) and hook callback paths shown in the authorization panel. URLs are now shielded from inline emphasis and render verbatim.
+
+## 0.58.1
+
+### Patch Changes
+
+- 7362a65: Keep Anthropic provider-executed server-tool results out of the local approval-resume repair so `srvtoolu_*` results stay provider-owned instead of replaying as generic tool results.
+- f9ba08b: Provide sourcemaps when Ash injects the Node ESM compatibility banner into authored module bundles, suppressing Rolldown sourcemap warnings during agent startup.
+- cac284c: Dedup inbound Slack events by `event_id` within a process so retried webhook deliveries no longer trigger the agent more than once.
+
 ## 0.58.0
 
 ### Minor Changes

package/dist/docs/public/advanced/execution-model-and-security.md

@@ -0,0 +1,319 @@
+---
+title: "Execution Model & Security"
+description: "Where your code runs, what has access to what, and how secrets flow through the system."
+---
+
+Ash agents run across two execution contexts with a trust boundary between them.
+
+## Execution Contexts
+
+Your agent has two execution contexts: the **app runtime** and the **sandbox**.
+
+The **app runtime** is where your agent code runs — tool implementations, model calls, MCP
+connections, state management, observability, and durable execution. It has `process.env`, your
+secrets, and full Node.js. On Vercel, this runs inside
+[Vercel Functions](https://vercel.com/docs/functions).
+
+The **sandbox** is an isolated environment. The model runs shell commands here via the built-in
+`bash`, `read_file`, and `write_file` tools. It has its own filesystem (`/workspace`) but no access
+to `process.env`, secrets, or the app runtime. On Vercel, each sandbox runs in a
+[Vercel Sandbox](https://vercel.com/docs/sandbox) microVM with hardware-level isolation. See
+[Sandboxes](../sandbox.md) for the full API.
+
+|                         | App Runtime  | Sandbox               |
+| ----------------------- | ------------ | --------------------- |
+| `process.env` / secrets | Yes          | No                    |
+| Node.js / your code     | Yes          | No                    |
+| Network                 | Unrestricted | Controlled by policy  |
+| Filesystem              | App's own    | Isolated `/workspace` |
+
+Everything except sandbox shell commands runs in the app runtime.
+
+## Durable Execution
+
+Agent turns run inside [Vercel Workflow](https://vercel.com/docs/workflow):
+
+- If the app runtime crashes mid-turn, Workflow resumes from the last step boundary.
+- Durable state is serialized at step boundaries, so sessions survive across invocations.
+- A session can span many requests over days or weeks without losing context.
+
+Ash manages the Workflow lifecycle — you don't configure it directly. Sessions are durable by
+default.
+
+## The Agent Loop
+
+Each turn follows the same cycle: model call, tool calls, results, another model call, until the
+model produces a final response.
+
+```mermaid
+sequenceDiagram
+  participant M as Model
+  participant A as App
+  participant S as Sandbox
+  M->>A: your tool
+  A->>A: execute
+  A->>M: result
+  M->>A: bash
+  A->>S: proxy
+  S->>A: stdout
+  A->>M: result
+```
+
+All tools — including the built-in `bash`, `read_file`, and `write_file` — run in the app runtime.
+The built-in tools proxy requests to the sandbox, where commands execute and files are read and
+written, then return results back to the model. The model sees tool definitions and results — never
+your secrets.
+
+## Data Flow Examples
+
+### `write_file` — app runtime proxies into sandbox
+
+The model writes a file. The tool runs in the app runtime, which authenticates to the sandbox
+automatically via Vercel OIDC and proxies the write.
+
+```mermaid
+sequenceDiagram
+  participant M as Model
+  participant A as App
+  participant S as Sandbox
+
+  M->>A: write_file
+  A->>A: validate path
+  A->>S: write via OIDC
+  S->>S: /workspace
+  S->>A: ok
+  A->>M: result
+```
+
+### Custom tool — runs in the app runtime
+
+Custom tools run in the app runtime as regular JavaScript. They can call external APIs using secrets
+from `process.env`, interact with the sandbox via `ctx.getSandbox()`, or both.
+
+```ts
+// agent/tools/get_deployments.ts
+import { defineTool } from "experimental-ash/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description: "List recent deployments for a project.",
+  inputSchema: z.object({
+    projectId: z.string(),
+  }),
+  async execute(input) {
+    const res = await fetch(`https://api.vercel.com/v6/deployments?projectId=${input.projectId}`, {
+      headers: { authorization: `Bearer ${process.env.VERCEL_API_TOKEN}` },
+    });
+    const { deployments } = await res.json();
+    return deployments.map((d: any) => ({
+      id: d.uid,
+      url: d.url,
+      state: d.state,
+    }));
+  },
+});
+```
+
+```mermaid
+sequenceDiagram
+  participant M as Model
+  participant A as App
+  participant API as Vercel API
+
+  M->>A: get_deployments
+  A->>A: read env token
+  A->>API: GET with Bearer
+  API->>A: deployments
+  A->>M: results
+
+  note over M,A: Model never sees the token
+```
+
+This is the typical pattern for most integrations. Your tool has full access to secrets and returns
+only what the model needs.
+
+### MCP connection — framework manages auth
+
+[MCP connections](../connections.mdx) expose third-party tools without writing executor code. The
+framework handles discovery and injects authentication headers automatically.
+
+```ts
+// agent/connections/linear.ts
+import { defineMcpClientConnection } from "experimental-ash/connections";
+
+export default defineMcpClientConnection({
+  url: "https://mcp.linear.app/sse",
+  description: "Linear workspace — issues, projects, cycles, and comments.",
+  auth: {
+    getToken: async () => ({ token: process.env.LINEAR_API_TOKEN! }),
+  },
+});
+```
+
+```mermaid
+sequenceDiagram
+  participant M as Model
+  participant A as App
+  participant MCP as MCP Server
+
+  M->>A: connection_search
+  A->>A: resolve token
+  A->>MCP: listTools + Bearer
+  MCP->>A: available tools
+  A->>M: tools
+
+  M->>A: list_issues
+  A->>MCP: tools/call + Bearer
+  MCP->>A: issues
+  A->>M: issues
+
+  note over A: Token cached per-step
+  note over M,A: Model never sees the token
+```
+
+The model discovers tools via `connection_search` and calls them by name. The framework resolves the
+token from `getToken()`, caches it per-step (never serialized to durable state), and injects it into
+every MCP request.
+
+### OAuth via Vercel Connect — interactive auth
+
+When a connection needs user authorization, Ash suspends the turn and orchestrates an OAuth flow via
+[Vercel Connect](https://vercel.com/docs/connect).
+
+```ts
+// agent/connections/linear.ts
+import { connect } from "@vercel/connect/ash";
+import { defineMcpClientConnection } from "experimental-ash/connections";
+
+export default defineMcpClientConnection({
+  url: "https://mcp.linear.app/sse",
+  description: "Linear workspace — issues, projects, cycles, and comments.",
+  auth: connect("linear"),
+});
+```
+
+```mermaid
+sequenceDiagram
+  participant M as Model
+  participant A as App
+  participant U as User
+  participant O as OAuth
+  participant MCP as MCP Server
+
+  M->>A: list_issues
+  A->>MCP: tools/call
+  MCP->>A: 401
+
+  A->>A: start auth
+  A->>M: auth required
+  note over M,A: Turn suspends
+
+  U->>O: grant access
+  O->>A: callback
+  A->>A: complete auth
+
+  note over M,A: Turn resumes
+
+  A->>MCP: tools/call + Bearer
+  MCP->>A: issues
+  A->>M: issues
+```
+
+The first call returns 401. Ash starts the OAuth flow and suspends the turn. After the user
+authorizes, the OAuth provider redirects back, Ash caches the token, and the tool re-executes. The
+token is never serialized to durable state and never visible to the model.
+
+## Sandbox Security
+
+The sandbox is isolated by default:
+
+| Property       | Behavior                                                                                 |
+| -------------- | ---------------------------------------------------------------------------------------- |
+| **Filesystem** | Isolated `/workspace`. Seeded from `agent/sandbox/workspace/`, persists across requests. |
+| **Secrets**    | No `process.env`, no app runtime access. Secrets cannot leak to the sandbox.             |
+| **Network**    | Controlled by policy: `"allow-all"` (default), `"deny-all"`, or per-domain allow-list.   |
+
+When the model needs authenticated network access from inside the sandbox — for example,
+`git clone` on a private repo — and you can't route the request through a tool or connection, use
+credential brokering.
+
+### Credential Brokering
+
+When using [Vercel Sandbox](https://vercel.com/docs/sandbox) as your sandbox backend, credential
+brokering injects auth headers at the sandbox's network firewall. The secret stays in the app
+runtime — the sandbox process never sees it.
+
+```mermaid
+sequenceDiagram
+  participant M as Model
+  participant A as App
+  participant S as Sandbox
+  participant GH as github.com
+
+  M->>A: bash git clone
+  A->>S: run command
+  S->>S: egress to github.com
+  note over S: Firewall injects auth header
+  S->>GH: request + auth
+  GH->>S: response
+  S->>A: stdout
+  A->>M: stdout
+```
+
+Configure it in the sandbox `onSession` hook. The `transform` injects headers for matching domains
+at the firewall — the sandbox process only sees the response, never the credential:
+
+```ts
+// agent/sandbox/sandbox.ts
+import { defineSandbox } from "experimental-ash/sandbox";
+
+export default defineSandbox({
+  async onSession({ use }) {
+    const ghToken = process.env.GITHUB_TOKEN;
+    await use({
+      networkPolicy: {
+        allow: {
+          "github.com": [
+            {
+              transform: [
+                { headers: { authorization: `Basic ${btoa(`x-access-token:${ghToken}`)}` } },
+              ],
+            },
+          ],
+          "*": [],
+        },
+      },
+    });
+  },
+});
+```
+
+The `"*": []` entry keeps general egress open. The sandbox can `git clone` private repos and `curl`
+the GitHub API without ever seeing the token.
+
+When the credential is resolved mid-turn, use `setNetworkPolicy` on the live sandbox handle:
+
+```ts
+const sandbox = await ctx.getSandbox();
+await sandbox.setNetworkPolicy({
+  allow: {
+    "github.com": [
+      {
+        transform: [{ headers: { authorization: `Basic ${btoa(`x-access-token:${token}`)}` } }],
+      },
+    ],
+    "*": [],
+  },
+});
+```
+
+See [Sandboxes — Network Policies](../sandbox.md#network-policies) for the full Ash policy API and
+[Vercel Sandbox — Credential Brokering](https://vercel.com/docs/sandbox/concepts/firewall#credentials-brokering)
+for the underlying platform mechanism.
+
+## What To Read Next
+
+- [Tools](../tools.mdx) — defining typed tools that run in the app runtime.
+- [Connections](../connections.mdx) — MCP server connections with static tokens or OAuth.
+- [Sandboxes](../sandbox.md) — lifecycle, backends, and network policies.
+- [Sessions And Streaming](./runs-and-streaming.md) — the HTTP API and session lifecycle.

package/dist/docs/public/advanced/meta.json

@@ -1,6 +1,7 @@
 {
   "title": "Advanced",
   "pages": [
+    "execution-model-and-security",
     "project-layout",
     "context-control",
     "hooks",

package/dist/docs/public/tools.mdx

@@ -101,6 +101,57 @@ The `ctx` parameter passed to `execute` is the primary way to access runtime sta
 
 These are available inside `execute` and other active authored runtime execution contexts.
 
+## Tool Authorization
+
+A tool can declare its own authorization strategy with the `auth` field. Use it when the tool calls
+a service behind OAuth (for example an Okta-protected API) and you want Ash to drive the sign-in
+flow, cache the resulting token, and re-run the tool after the user authorizes — without standing up
+a separate connection.
+
+`auth` accepts the same shapes as a connection's `auth`: `connect("...")` from `@vercel/connect/ash`
+for Vercel Connect-managed OAuth, a custom interactive definition, or a plain `{ getToken }` object
+for static or pre-provisioned credentials.
+
+`agent/tools/list_okta_groups.ts`
+
+```ts
+import { defineTool } from "experimental-ash/tools";
+import { connect } from "@vercel/connect/ash";
+import { z } from "zod";
+
+export default defineTool({
+  description: "List the caller's Okta groups.",
+  inputSchema: z.object({}),
+  auth: connect("okta"),
+  async execute(_input, ctx) {
+    // Resolves the per-user token. If the user has not signed in, this
+    // suspends the turn, the channel shows a "Sign in" affordance, and
+    // the tool re-runs after the OAuth callback completes.
+    const { token } = await ctx.getToken();
+    const res = await fetch("https://api.okta-proxy.internal/groups", {
+      headers: { authorization: `Bearer ${token}` },
+    });
+    return await res.json();
+  },
+});
+```
+
+When the tool declares `auth`, the `ctx` passed to `execute` gains two accessors:
+
+- `ctx.getToken()` resolves the bearer for the declared strategy, consulting the per-step token cache
+  before invoking the authored `getToken`. For interactive strategies a cache miss suspends the turn
+  on a framework-owned callback URL and re-runs the tool after sign-in.
+- `ctx.requireAuth()` explicitly throws `ConnectionAuthorizationRequiredError` to gate the tool on
+  authorization without resolving a token first. The runtime converts it into the same consent
+  prompt.
+
+Throwing `ConnectionAuthorizationRequiredError` anywhere inside `execute` — directly, via
+`ctx.requireAuth()`, or implicitly from `ctx.getToken()` — triggers the consent flow. The
+authorization state (token cache and callback URL) is keyed by the tool's name, the same way
+connection auth is keyed by the connection name.
+
+Calling `ctx.getToken()` or `ctx.requireAuth()` on a tool that does **not** declare `auth` throws.
+
 ## When A Tool Runs
 
 Ash does not execute authored tools during discovery.