experimental-ash 0.58.1 → 0.59.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # 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

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.

package/dist/skills/v0-ash-onboarding/SKILL.md

@@ -0,0 +1,308 @@
+---
+name: v0-ash-onboarding
+description: Use when bootstrapping, testing, or debugging an Ash Web Chat agent inside a v0 preview or v0 sandbox. Runs create-experimental-ash-agent in-place with v0-safe flags, avoids Vercel Services/vercel dev, and verifies that the v0 preview shows the Next.js chat UI.
+---
+
+# v0 Ash onboarding
+
+Scaffold an Ash Web Chat agent into the current v0 project root and verify the browser preview. This skill is for v0 dev/preview only.
+
+## Ground rules
+
+- Work in the v0 project root. In v0 this is usually `/vercel/share/v0-project`; confirm with `pwd` and `ls`.
+- Do not create a child project directory. Use `--in-place` and omit `<name>`. Do not invent names like `v0-preview`.
+- Do not run `vercel login`, `vercel deploy`, `vercel dev`, `vercel env pull`, or Vercel CLI auth commands.
+- Do not pass `--project`, `--team`, or `--channels slack`.
+- Do not use old flags such as `--local-only` or `--no-deploy`. Use `--skip-vercel`; it also skips deployment.
+- Do not ask for or set any Vercel API token such as `VERCEL_TOKEN` or `VERCEL_API_TOKEN`. It is not required for this v0 dev/preview flow because `--skip-vercel` skips Vercel project provisioning, Services config, env pull, and deployment.
+- Do not use v0's "Add Environment Variable" request UI or "Generate" flow for `AI_GATEWAY_API_KEY`. This flow consumes v0-managed env injection; a missing key is a failed env-injection probe, not a prompt to ask the user for a secret.
+- Do not start a separate `ash dev` process. The Web Chat scaffold uses `next dev`; `withAsh()` starts the app-local Ash dev server and rewrites same-origin `/ash/*` requests.
+- Do not hand-edit `next.config.ts` or `vercel.json` as the normal path. The create CLI should produce the v0-safe config.
+- Do not repair a bad `.ash/next-dev-server.json` origin by setting `ASH_BASE_URL` as the normal path. The registry origin for `withAsh()` development must be loopback; an external origin such as `https://rolldown.rs` means the installed Ash package parsed the wrong URL from dev-server output or a stale registry survived.
+
+## Inputs
+
+Collect these before running the CLI:
+
+- `model`: the model id to bake into `agent/agent.ts`, for example `openai/gpt-5-mini`.
+- Agent behavior: any instructions, skills, tools, or UI changes the user wants after the base scaffold works.
+
+Do not ask the user for an AI Gateway key at model-planning time or after a failed env probe. The sandbox and `/vercel/share/.env.project` may not exist until the first terminal/tool action has initialized the VM, and it may not be reliable until the preview has settled. Treat `AI_GATEWAY_API_KEY` as the final verification input: after the scaffold, route rewrite, and UI checks pass, source `/vercel/share/.env.project` and hydrate a project-local `.env.local` fallback. Only use `--gateway-api-key` when the user explicitly supplies a BYOK key before this flow.
+
+Do not ask the user for `VERCEL_TOKEN`, `VERCEL_API_TOKEN`, or another Vercel API token at any point in this flow. If a tool or model says a Vercel token is missing, treat that as using the wrong path and continue with `--skip-vercel` plus the v0-managed `AI_GATEWAY_API_KEY` checks below.
+
+## Dev-server invariant
+
+The v0 preview's `next dev` process must start after the scaffold has written `next.config.ts`. Next.js route rewrites are process config, so an already-running pre-scaffold `next dev` process can keep serving stale routes even after the file exists on disk.
+
+Make this the normal path:
+
+1. Stop any pre-scaffold `next dev` process.
+2. Run create in place.
+3. Verify `next.config.ts` contains `withAsh(nextConfig, { configureVercelJson: false })`.
+4. Start `pnpm dev` once.
+5. Probe `/ash/v1/health`.
+
+Do not treat a restart after `/ash/v1/session` 404s as the happy path. A restart is only recovery for a missed preflight.
+
+## Step 1. Check the CLI surface
+
+Run the help command from the v0 root:
+
+```bash
+npx create-experimental-ash-agent@latest --help
+```
+
+The help output must include `--in-place`, `--skip-vercel`, and `--gateway-api-key`.
+
+If any flag is missing, stop and report that the published create CLI is stale for this v0 flow. Do not recreate the old workaround by moving child directories, adding `concurrently`, replacing `next.config.ts`, or writing Vercel Services config by hand.
+
+## Step 2. Scaffold in place
+
+Before scaffolding, make sure no stale preview dev server is already running from the pre-scaffold project:
+
+```bash
+pgrep -af "next dev|next/dist/bin/next dev" || true
+```
+
+If that command prints a `next dev` process, stop the preview before running create. Use v0's preview stop/restart control if available; otherwise kill only the printed `next dev` PID. The goal is for the first post-bootstrap `next dev` start to happen after `next.config.ts` already contains `withAsh(...)`. Do not let an already-running Next process carry pre-scaffold config into the chat test.
+
+Run create without waiting on env injection:
+
+```bash
+npx create-experimental-ash-agent@latest \
+  --in-place \
+  --model "$MODEL" \
+  --channels web \
+  --skip-vercel \
+  --disable-git \
+  -y \
+  --json
+```
+
+With `--skip-vercel`, create may warn that no project or API key is linked. Do not treat that as a failure; the v0-managed env is checked as the final verification step after the preview settles. Do not respond to that warning by asking for a Vercel token.
+
+`--disable-git` skips the create CLI's local `git init` and initial commit. v0 owns project history for this workflow.
+
+## Step 3. Verify generated files
+
+Check the exact files v0's preview detector sees:
+
+```bash
+test -f agent/agent.ts
+test -f app/page.tsx
+test -f next.config.ts
+node -e 'const p=require("./package.json"); if (p.scripts?.dev !== "next dev") throw new Error(`unexpected dev script: ${p.scripts?.dev}`)'
+grep -q 'configureVercelJson: false' next.config.ts
+```
+
+Then check no stale supported Next config can shadow the generated Ash config:
+
+```bash
+competing_next_configs="$(ls next.config.js next.config.mjs next.config.mts 2>/dev/null || true)"
+if [ -n "$competing_next_configs" ]; then
+  echo "competing Next config remains; merge needed settings into next.config.ts and remove the competing file before starting the preview"
+  printf "%s\n" "$competing_next_configs"
+  exit 1
+fi
+```
+
+If `next.config.mjs` exists beside `next.config.ts`, Next.js loads `next.config.mjs` first and ignores the generated `withAsh(...)` config. That produces a Next.js 404 for `/ash/v1/session` even though `next.config.ts` looks correct on disk.
+
+If the create CLI warns about a competing Next config, or the shell check above prints one, inspect each printed file before removing it. Preserve any needed settings in `next.config.ts`; for v0's common defaults that usually means keeping this shape inside the generated file:
+
+```ts
+const nextConfig: NextConfig = {
+  images: { unoptimized: true },
+  typescript: { ignoreBuildErrors: true },
+};
+```
+
+After preserving needed settings, remove the competing `next.config.js`, `next.config.mjs`, or `next.config.mts` before starting the preview. Do not start `pnpm dev` while more than one supported Next config file remains.
+
+Then check Services is absent:
+
+```bash
+if [ -f vercel.json ] && grep -q experimentalServices vercel.json; then
+  echo "stale Vercel Services config remains in vercel.json"
+  exit 1
+fi
+```
+
+If `vercel.json` still contains `experimentalServices`, this is stale state from a previous attempt or a create CLI bug. Remove that stale Services config before testing the preview, but call it out explicitly.
+
+## Step 4. Install and run
+
+Install dependencies if v0 has not already done it:
+
+```bash
+pnpm install
+```
+
+Let v0 run the preview, or start it manually:
+
+```bash
+pnpm dev
+```
+
+Expected dev command: `next dev`. Do not run `vercel dev`. Do not run `ash dev` in a second terminal.
+
+If Step 2 stopped the pre-scaffold preview, this is the one clean start that should load the generated `next.config.ts`. Next's route rewrites are config-level state, so do not rely on page HMR if an old process survived the preflight.
+
+Verify that the active process is the post-scaffold `next dev` process:
+
+```bash
+pgrep -af "next dev" || true
+```
+
+If an old `next dev` process was already running before the scaffold and was not stopped, stop that process before testing chat. A valid run has a `next dev` process that started after `next.config.ts` was generated.
+
+For local v0 source semantics, v0 detects `next dev` as the preview command and exposes the detected port. If live v0 instead requires the app to bind an arbitrary `$DEV_PORT`, report that as a scaffold gap. Do not hide it by hand-patching the dev script unless the user explicitly asks for that experiment.
+
+## Step 5. Verify the Ash route rewrite
+
+Before sending a chat message, probe the same-origin Ash health route through the Next preview:
+
+```bash
+curl -i "http://127.0.0.1:${DEV_PORT:-3000}/ash/v1/health"
+```
+
+Expected: an HTTP 2xx response from Ash. A Next.js HTML 404 page for `/ash/v1/health` or `/ash/v1/session` means the active Next server did not load the `withAsh()` rewrite.
+
+If the probe returns a Next.js 404, check the generated config and stale Services state:
+
+```bash
+grep -R "withAsh\\|configureVercelJson\\|experimentalServices" next.config.* vercel.json 2>/dev/null || true
+```
+
+Expected:
+
+- `next.config.ts` imports `withAsh` from `experimental-ash/next`.
+- `next.config.ts` exports `withAsh(nextConfig, { configureVercelJson: false })`.
+- `vercel.json` is absent or does not contain `experimentalServices`.
+
+If the files are correct but the probe still returns a Next.js 404, restart the v0 preview/dev server and run the probe again. Do not debug AI Gateway credentials until this route probe passes; missing credentials do not make Next serve its own 404 page.
+
+If the files stay correct and the 404 persists after restart, inspect whether the active server ever resolved the Ash rewrite:
+
+```bash
+pgrep -af "next dev|ash.js dev|ash dev" || true
+test -f .ash/next-dev-server.json && cat .ash/next-dev-server.json || echo "missing .ash/next-dev-server.json"
+```
+
+- If `.ash/next-dev-server.json` is missing after the `/ash/v1/health` probe, the running Next process did not call the `withAsh()` rewrite function. Restart the v0 preview process that owns `${DEV_PORT}`, not a second `pnpm dev` process on a different port.
+- If `.ash/next-dev-server.json` exists, probe the registered Ash origin directly:
+
+```bash
+node -e 'const fs=require("fs"); const r=JSON.parse(fs.readFileSync(".ash/next-dev-server.json","utf8")); console.log(r.origin)'
+node -e 'const fs=require("fs"); const r=JSON.parse(fs.readFileSync(".ash/next-dev-server.json","utf8")); const h=new URL(r.origin).hostname; if (!(h==="localhost" || h==="::1" || h.startsWith("127."))) { console.error(`Ash dev server registry origin is not loopback: ${r.origin}`); process.exit(1); }'
+curl -i "$(node -e 'const fs=require("fs"); const r=JSON.parse(fs.readFileSync(".ash/next-dev-server.json","utf8")); process.stdout.write(r.origin)')/ash/v1/health"
+```
+
+If the loopback-origin check fails, remove `.ash/next-dev-server.json`, reinstall or update `experimental-ash`, and restart the post-scaffold `next dev` process. Do not start a separate fixed-port Ash server and do not patch `ASH_BASE_URL` unless the user explicitly asks for a temporary experiment; that hides the `withAsh()` discovery bug.
+
+If direct Ash health passes but same-origin `/ash/v1/health` is still a Next.js 404, the active Next rewrite is missing or stale. If direct Ash health fails, debug the spawned Ash dev server before testing chat.
+
+## Step 6. Browser verification
+
+Open the v0 preview, preferably through the v0/browser tool:
+
+```bash
+agent-browser open "http://localhost:${DEV_PORT:-3000}"
+```
+
+The first viewport should show the Ash Web Chat UI, not the Ash backend landing page. A successful compile is not enough.
+
+Before moving to the final env step, confirm all of these:
+
+- Typing in the composer leaves visible text in the textarea.
+- The send button is clickable after typing text.
+
+If the send button stays disabled after typing text, inspect `app/_components/agent-chat.tsx`. Older scaffolds duplicated textarea state in `AgentChat` and used that duplicate state to pass `disabled` to `PromptInputSubmit`. Remove the `inputText` state, render `<PromptInputTextarea placeholder="Send a message…" />`, and render `<PromptInputSubmit onStop={agent.stop} status={agent.status} />`. `PromptInput` already captures the form text and `handleSubmit` already no-ops for empty trimmed messages.
+
+If the preview shows "The agent is up and accepting messages", inspect these before changing code:
+
+```bash
+grep -R "experimentalServices\\|vercel dev\\|ash dev\\|concurrently\\|configureVercelJson" package.json next.config.* vercel.json 2>/dev/null || true
+```
+
+Likely causes:
+
+- `vercel.json` still contains `experimentalServices`, so v0 selected the Services path.
+- The CLI was stale and did not render `configureVercelJson: false`.
+- The project was not scaffolded in place and v0 is previewing the wrong root.
+- Live v0 is watching a non-3000 `$DEV_PORT` that the generated `next dev` script does not bind. Report this as a failed acceptance check for the scaffold.
+
+Do not send the final chat message yet. The AI Gateway key is the last step because v0's managed env file is most reliable after the sandbox and preview have settled.
+
+If a route probe or browser request fails with a Next.js HTML 404 for `/ash/v1/session`, return to Step 5. That failure is a missing active rewrite, not a model or credential failure.
+
+## Step 7. Hydrate env and send a message
+
+After the preview route and UI checks pass, wait for v0's managed env file, then hydrate `.env.local` without printing the secret:
+
+```bash
+bash -lc 'for i in $(seq 1 60); do set -a; . /vercel/share/.env.project 2>/dev/null; set +a; [ -n "${AI_GATEWAY_API_KEY:-}" ] && break; sleep 1; done; if [ -z "${AI_GATEWAY_API_KEY:-}" ]; then echo "AI_GATEWAY_API_KEY missing from /vercel/share/.env.project after waiting for v0 env injection"; exit 1; fi; umask 077; { grep -v "^AI_GATEWAY_API_KEY=" .env.local 2>/dev/null || true; printf "AI_GATEWAY_API_KEY=%s\n" "$AI_GATEWAY_API_KEY"; } > .env.local.tmp && mv .env.local.tmp .env.local'
+```
+
+If that command reports the key is missing after the wait, report that v0 env injection is not ready or did not provide `AI_GATEWAY_API_KEY`. Do not ask the user for a key, do not open v0's "Add Environment Variable" UI, and do not press "Generate"; stop for user direction or retry the wait if the sandbox was still settling.
+
+Do not decide the key is unavailable from a bare `printenv AI_GATEWAY_API_KEY`; generic v0 terminal commands may not source `/vercel/share/.env.project`.
+
+Verify the env files without printing secret values:
+
+```bash
+bash -lc 'for f in .env.local /vercel/share/.env.project; do echo "== $f =="; test -f "$f" && grep -E "^(AI_GATEWAY_API_KEY|ANTHROPIC_AUTH_TOKEN)=" "$f" | sed "s/=.*/=<redacted>/" || echo missing; done'
+```
+
+After the hydration command, `.env.local` should contain `AI_GATEWAY_API_KEY` copied from `/vercel/share/.env.project`. If the user explicitly supplied a BYOK key before this flow, `.env.local` may contain that value; otherwise do not request one. If `.env.local` is missing but `/vercel/share/.env.project` has the key, re-run the hydration command.
+
+Do not debug `AI_GATEWAY_KEY` as the required variable; v0 and Ash use `AI_GATEWAY_API_KEY`.
+
+Then verify v0's source order resolves a usable environment:
+
+```bash
+bash -lc 'set -a; . .env.local 2>/dev/null; . .env.development.local 2>/dev/null; . /vercel/share/.env.project 2>/dev/null; set +a; node -e "console.log({ AI_GATEWAY_API_KEY: Boolean(process.env.AI_GATEWAY_API_KEY), ANTHROPIC_AUTH_TOKEN: Boolean(process.env.ANTHROPIC_AUTH_TOKEN) })"'
+```
+
+If the preview server was already running before `.env.local` existed, restart it once after hydration so `next dev` and the spawned `ash dev` process inherit the key. Then inspect the live process envs, redacted:
+
+```bash
+pgrep -af "next dev|ash.js dev|ash dev" || true
+PID=<pid>
+tr '\0' '\n' < /proc/$PID/environ \
+  | grep -E '^(AI_GATEWAY_API_KEY|ANTHROPIC_AUTH_TOKEN)=' \
+  | sed 's/=.*/=<redacted>/'
+```
+
+Check both the `next dev` process and the spawned `ash dev` process.
+
+- If `/vercel/share/.env.project` has `AI_GATEWAY_API_KEY` but `next dev` does not, v0 likely started the preview before the env file existed or used a start path that skipped `getSourceEnvPrefix()`. Restart the preview and re-check.
+- If `next dev` has `AI_GATEWAY_API_KEY` but the spawned `ash dev` process does not, treat it as an Ash child-process env propagation bug.
+- If `.env.local` has a good `AI_GATEWAY_API_KEY` but `/vercel/share/.env.project` has the same key empty or stale, v0's source order makes `/vercel/share/.env.project` win. Remove or refresh the stale v0-managed value before restarting the preview.
+
+Finally, send one browser message:
+
+- Sending creates a `POST /ash/v1/session` request.
+- The assistant streams a response.
+
+If chat fails with missing AI Gateway credentials, do not guess from an interactive shell. Use the env file and process checks above.
+
+If chat fails with a Next.js HTML 404 for `POST /ash/v1/session`, return to Step 5. That failure is a missing active rewrite, not a model or credential failure.
+
+## Step 8. Apply the user's agent changes
+
+After the base chat works, edit the Ash project:
+
+- `agent/instructions.md` for behavior and personality.
+- `agent/skills/*.md` for durable knowledge and procedures.
+- `agent/tools/*.ts` for tools.
+- `app/**` for UI changes.
+
+Tool definitions import from `experimental-ash/tools`:
+
+```ts
+import { defineTool } from "experimental-ash/tools";
+```
+
+Use `inputSchema` for tool input schemas.

package/dist/src/cli/dev/tui/markdown.js

@@ -1,3 +1,3 @@
 import{visibleLength}from"./terminal-text.js";const ansi={bold:`\x1B[1m`,boldOff:`\x1B[22m`,italic:`\x1B[3m`,italicOff:`\x1B[23m`};function renderMarkdown(e){let t=e.split(`
 `),n=[];for(let e=0;e<t.length;e+=1){let r=parseTable(t,e);if(r!=null){n.push(...renderTable(r)),e=r.endIndex-1;continue}n.push(renderMarkdownLine(t[e]??``))}return n.join(`
-`)}function renderMarkdownLine(e){if(e.startsWith(`### `))return renderInlineMarkdown(`▶ ${e.slice(4)}`);if(e.startsWith(`## `))return renderInlineMarkdown(`■ ${e.slice(3)}`);if(e.startsWith(`# `))return renderInlineMarkdown(`█ ${e.slice(2)}`);let t=e.match(/^(\s*)[-+*]\s+(.*)$/);if(t){let[,e,n=``]=t;return renderInlineMarkdown(`${e}•${n.length>0?` ${n}`:``}`)}return/^\d+\. /.test(e)?renderInlineMarkdown(e.replace(/^(\d+)\. /,`$1. `)):e.startsWith(`> `)?renderInlineMarkdown(`│ ${e.slice(2)}`):renderInlineMarkdown(e)}function renderInlineMarkdown(e){return e.replaceAll(/`([^`]+)`/g,`$1`).replaceAll(/\*\*([^*\n]+)\*\*/g,`${ansi.bold}$1${ansi.boldOff}`).replaceAll(/__([^_\n]+)__/g,`${ansi.bold}$1${ansi.boldOff}`).replaceAll(/\*([^*\n]+)\*/g,`${ansi.italic}$1${ansi.italicOff}`).replaceAll(/_([^_\n]+)_/g,`${ansi.italic}$1${ansi.italicOff}`)}function parseTable(e,t){let n=parseTableCells(e[t]??``);if(n==null||n.length<2)return;let r=parseTableCells(e[t+1]??``);if(r==null||r.length!==n.length)return;let i=parseTableAlignments(r);if(i==null)return;let a=[],o=t+2;for(;o<e.length;){let t=parseTableCells(e[o]??``);if(t==null)break;a.push(normalizeTableRow(t,n.length)),o+=1}return{alignments:i,endIndex:o,header:n,rows:a}}function parseTableCells(e){if(!e.includes(`|`))return;let t=e.trim();t.startsWith(`|`)&&(t=t.slice(1)),t.endsWith(`|`)&&!t.endsWith(`\\|`)&&(t=t.slice(0,-1));let n=[],r=``;for(let e=0;e<t.length;e+=1){let i=t[e],a=t[e+1];if(i===`\\`&&a===`|`){r+=`|`,e+=1;continue}if(i===`|`){n.push(r.trim()),r=``;continue}r+=i}return n.push(r.trim()),n}function parseTableAlignments(e){let t=[];for(let n of e){let e=n.match(/^(:)?-{3,}(:)?$/);if(e==null)return;let[,r,i]=e;t.push(r!=null&&i!=null?`center`:i==null?`left`:`right`)}return t}function normalizeTableRow(e,t){return Array.from({length:t},(t,n)=>e[n]??``)}function renderTable(n){let r=n.header.map(e=>`${ansi.bold}${renderInlineMarkdown(e)}${ansi.boldOff}`),i=n.rows.map(e=>e.map(renderInlineMarkdown)),a=[r,...i],o=n.alignments.map((t,n)=>Math.max(3,...a.map(t=>visibleLength(t[n]??``))));return[formatTableRow(r,o,n.alignments),o.map(e=>`─`.repeat(e)).join(`  `),...i.map(e=>formatTableRow(e,o,n.alignments))]}function formatTableRow(e,t,n){return e.map((e,r)=>alignTableCell(e,t[r]??0,n[r]??`left`)).join(`  `)}function alignTableCell(t,n,r){let i=Math.max(0,n-visibleLength(t));if(r===`right`)return`${` `.repeat(i)}${t}`;if(r===`center`){let e=Math.floor(i/2),n=i-e;return`${` `.repeat(e)}${t}${` `.repeat(n)}`}return`${t}${` `.repeat(i)}`}export{renderMarkdown};
+`)}function renderMarkdownLine(e){if(e.startsWith(`### `))return renderInlineMarkdown(`▶ ${e.slice(4)}`);if(e.startsWith(`## `))return renderInlineMarkdown(`■ ${e.slice(3)}`);if(e.startsWith(`# `))return renderInlineMarkdown(`█ ${e.slice(2)}`);let t=e.match(/^(\s*)[-+*]\s+(.*)$/);if(t){let[,e,n=``]=t;return renderInlineMarkdown(`${e}•${n.length>0?` ${n}`:``}`)}return/^\d+\. /.test(e)?renderInlineMarkdown(e.replace(/^(\d+)\. /,`$1. `)):e.startsWith(`> `)?renderInlineMarkdown(`│ ${e.slice(2)}`):renderInlineMarkdown(e)}function renderInlineMarkdown(e){let n=[];return e.replaceAll(/https?:\/\/\S+/g,e=>{let t=`\uE000${n.length}\uE001`;return n.push(e),t}).replaceAll(/`([^`]+)`/g,`$1`).replaceAll(/\*\*([^*\n]+)\*\*/g,`${ansi.bold}$1${ansi.boldOff}`).replaceAll(/__([^_\n]+)__/g,`${ansi.bold}$1${ansi.boldOff}`).replaceAll(/\*([^*\n]+)\*/g,`${ansi.italic}$1${ansi.italicOff}`).replaceAll(/_([^_\n]+)_/g,`${ansi.italic}$1${ansi.italicOff}`).replaceAll(/\uE000(\d+)\uE001/g,(e,t)=>n[Number(t)]??``)}function parseTable(e,t){let n=parseTableCells(e[t]??``);if(n==null||n.length<2)return;let r=parseTableCells(e[t+1]??``);if(r==null||r.length!==n.length)return;let i=parseTableAlignments(r);if(i==null)return;let a=[],o=t+2;for(;o<e.length;){let t=parseTableCells(e[o]??``);if(t==null)break;a.push(normalizeTableRow(t,n.length)),o+=1}return{alignments:i,endIndex:o,header:n,rows:a}}function parseTableCells(e){if(!e.includes(`|`))return;let t=e.trim();t.startsWith(`|`)&&(t=t.slice(1)),t.endsWith(`|`)&&!t.endsWith(`\\|`)&&(t=t.slice(0,-1));let n=[],r=``;for(let e=0;e<t.length;e+=1){let i=t[e],a=t[e+1];if(i===`\\`&&a===`|`){r+=`|`,e+=1;continue}if(i===`|`){n.push(r.trim()),r=``;continue}r+=i}return n.push(r.trim()),n}function parseTableAlignments(e){let t=[];for(let n of e){let e=n.match(/^(:)?-{3,}(:)?$/);if(e==null)return;let[,r,i]=e;t.push(r!=null&&i!=null?`center`:i==null?`left`:`right`)}return t}function normalizeTableRow(e,t){return Array.from({length:t},(t,n)=>e[n]??``)}function renderTable(n){let r=n.header.map(e=>`${ansi.bold}${renderInlineMarkdown(e)}${ansi.boldOff}`),i=n.rows.map(e=>e.map(renderInlineMarkdown)),a=[r,...i],o=n.alignments.map((t,n)=>Math.max(3,...a.map(t=>visibleLength(t[n]??``))));return[formatTableRow(r,o,n.alignments),o.map(e=>`─`.repeat(e)).join(`  `),...i.map(e=>formatTableRow(e,o,n.alignments))]}function formatTableRow(e,t,n){return e.map((e,r)=>alignTableCell(e,t[r]??0,n[r]??`left`)).join(`  `)}function alignTableCell(t,n,r){let i=Math.max(0,n-visibleLength(t));if(r===`right`)return`${` `.repeat(i)}${t}`;if(r===`center`){let e=Math.floor(i/2),n=i-e;return`${` `.repeat(e)}${t}${` `.repeat(n)}`}return`${t}${` `.repeat(i)}`}export{renderMarkdown};

package/dist/src/compiled/.vendor-stamp.json

@@ -6,7 +6,7 @@
     "@chat-adapter/state-memory": "4.29.0",
     "chokidar": "5.0.0",
     "commander": "14.0.3",
-    "experimental-ai-sdk-code-mode": "1.0.10",
+    "experimental-ai-sdk-code-mode": "1.0.14",
     "@ai-sdk/google": "4.0.0-canary.75",
     "gray-matter": "4.0.3",
     "jose": "6.2.3",
@@ -28,5 +28,5 @@
     "zod": "4.4.3",
     "zod-validation-error": "5.0.0"
   },
-  "scriptHash": "d058df06982d76ea3f28a17d85e12bfd9d19a58aede5830e27938e6ee911c5f4"
+  "scriptHash": "ed1694db63648dbdf127975ce45e76877eb96ced163cb0c22b0d84b23f75fe42"
 }

package/dist/src/compiled/experimental-ai-sdk-code-mode/approval-continuation.d.ts

@@ -0,0 +1,71 @@
+import { generateText, type ModelMessage, streamText } from "ai";
+import type { CodeModeApprovalInterrupt, CodeModeApprovalResponse, CodeModeOptions, CodeModeToolExecutionOptions, CodeModeToolSet } from "./types.js";
+/**
+ * Returns true when a value is a code-mode approval interruption.
+ *
+ * An approval interruption is a `CodeModeInterrupt` whose payload kind is the
+ * reserved approval kind, so this also implies `isCodeModeInterrupt`.
+ */
+export declare function isCodeModeApprovalInterrupt(value: unknown): value is CodeModeApprovalInterrupt;
+/**
+ * Continues a code-mode invocation that previously returned an approval
+ * interruption.
+ *
+ * This is a thin adapter over `continueCodeModeInterrupt`: it validates the AI
+ * SDK approval response, maps it to a boolean approval resolution, and forces
+ * interrupt-mode approval so any further nested approvals interrupt as well.
+ */
+export declare function continueCodeModeApproval({ interrupt, approvalResponse, tools, options, toolExecutionOptions, }: {
+    interrupt: CodeModeApprovalInterrupt;
+    approvalResponse: CodeModeApprovalResponse;
+    tools: CodeModeToolSet;
+    options?: CodeModeOptions;
+    toolExecutionOptions?: Partial<CodeModeToolExecutionOptions>;
+}): Promise<unknown>;
+/**
+ * Builds AI SDK model messages that expose a code-mode nested approval as an
+ * approval request for the original inner tool name and input.
+ *
+ * The interruption id is used as the AI SDK approval id.
+ */
+export declare function toCodeModeApprovalMessages(interrupt: CodeModeApprovalInterrupt): ModelMessage[];
+/**
+ * Finds the AI SDK approval response for a stored code-mode approval
+ * interruption in a model message list.
+ */
+export declare function getCodeModeApprovalResponse(messages: ModelMessage[], interrupt: CodeModeApprovalInterrupt): CodeModeApprovalResponse | undefined;
+/**
+ * Finds a code-mode approval interruption in an AI SDK result-like object.
+ */
+export declare function getCodeModeApprovalInterrupt(result: unknown): CodeModeApprovalInterrupt | undefined;
+/**
+ * Runs `generateText` and annotates the returned result with any code-mode
+ * approval interruption and AI SDK approval messages.
+ */
+export declare function generateTextWithCodeModeApprovals(options: Parameters<typeof generateText>[0]): Promise<Awaited<ReturnType<typeof generateText>> & {
+    codeModeApproval: CodeModeApprovalInterrupt | undefined;
+    codeModeApprovalMessages: ModelMessage[];
+}>;
+/**
+ * Runs `streamText` and adds a `codeModeApproval` promise that resolves to any
+ * approval interruption found in the final tool results.
+ */
+export declare function streamTextWithCodeModeApprovals(options: Parameters<typeof streamText>[0]): ReturnType<typeof streamText> & {
+    codeModeApproval: Promise<CodeModeApprovalInterrupt | undefined>;
+};
+/**
+ * Wraps a ToolLoopAgent-like object so `generate`/`stream` results expose
+ * code-mode approval interruption metadata.
+ */
+export declare function wrapToolLoopAgentForCodeModeApprovals<T extends {
+    generate?: (...args: any[]) => Promise<unknown>;
+    stream?: (...args: any[]) => Promise<unknown>;
+}>(agent: T): T;
+/**
+ * Adds approval interruption metadata to a result-like object.
+ */
+export declare function attachCodeModeApprovalResult<T>(result: T): T & {
+    codeModeApproval: CodeModeApprovalInterrupt | undefined;
+    codeModeApprovalMessages: ModelMessage[];
+};
+//# sourceMappingURL=approval-continuation.d.ts.map

package/dist/src/compiled/experimental-ai-sdk-code-mode/approval.d.ts

@@ -0,0 +1,32 @@
+import type { CodeModeApprovalInterruptPayload, CodeModeApprovalResolution, CodeModeApprovalResponse, CodeModeInterruptPayload } from "./types.js";
+/**
+ * Reserved interruption payload kind for built-in nested tool approvals.
+ *
+ * Approval is implemented as a generic code-mode interruption tagged with this
+ * kind. Host tools must not use this kind for their own
+ * `requestCodeModeInterrupt` payloads.
+ *
+ * @internal
+ */
+export declare const CODE_MODE_TOOL_APPROVAL_KIND = "ai-sdk-code-mode/tool-approval";
+/**
+ * Returns true when a generic interruption payload is a built-in approval.
+ *
+ * @internal
+ */
+export declare function isCodeModeApprovalInterruptPayload(payload: CodeModeInterruptPayload): payload is CodeModeApprovalInterruptPayload;
+/**
+ * Validates an approval response from model/client history at runtime.
+ *
+ * @internal
+ */
+export declare function assertCodeModeApprovalResponse(value: unknown): asserts value is CodeModeApprovalResponse;
+/**
+ * Validates and normalizes the resolution used to resume an approval
+ * interruption. The generic interrupt machinery passes this resolution through
+ * `continueCodeModeInterrupt`; approval interrupts require a boolean decision.
+ *
+ * @internal
+ */
+export declare function normalizeApprovalResolution(resolution: unknown): CodeModeApprovalResolution;
+//# sourceMappingURL=approval.d.ts.map

package/dist/src/compiled/experimental-ai-sdk-code-mode/code-mode-tool.d.ts

@@ -0,0 +1,16 @@
+import type { Tool } from "ai";
+import type { CodeModeOptions, CodeModeToolInput, CodeModeToolSet } from "./types.js";
+/**
+ * Creates an AI SDK tool that executes code-mode TypeScript in an isolated
+ * sandbox.
+ *
+ * The generated tool description includes sandbox rules, available host tool
+ * signatures, return types when an AI SDK output schema is present, call
+ * examples, and fetch policy details when fetch is enabled.
+ *
+ * @param tools - Host tools that sandboxed code can call through `tools.name(input)`.
+ * @param options - Runtime, fetch, and approval options for every invocation of this tool.
+ * @returns An AI SDK tool whose input is `{ js: string }` and whose output is the sandbox return value.
+ */
+export declare function createCodeModeTool(tools: CodeModeToolSet, options?: CodeModeOptions): Tool<CodeModeToolInput, unknown>;
+//# sourceMappingURL=code-mode-tool.d.ts.map

package/dist/src/compiled/experimental-ai-sdk-code-mode/continuation-capability.d.ts

@@ -0,0 +1,33 @@
+import type { CodeModeContinuation, UnsignedCodeModeContinuation } from "./types.js";
+/**
+ * Sets the process-global continuation signing key.
+ *
+ * Hosts that need approval or interrupt continuations to survive process
+ * restarts must configure the same secret before creating and resuming
+ * continuations. Calling without arguments restores a random process-local key.
+ *
+ * @param key - Secret key bytes or UTF-8 string, or `undefined` to reset.
+ * @param options - Optional continuation signing policy.
+ */
+export declare function setCodeModeContinuationSigningKey(key?: string | Uint8Array, options?: {
+    maxAgeMs?: number;
+}): void;
+/**
+ * Signs a host-created continuation as an unforgeable bearer capability.
+ *
+ * @internal
+ */
+export declare function signCodeModeContinuation(continuation: UnsignedCodeModeContinuation): CodeModeContinuation;
+/**
+ * Verifies that a continuation was issued by this host and has not expired.
+ *
+ * @internal
+ */
+export declare function verifyCodeModeContinuation(continuation: CodeModeContinuation): void;
+/**
+ * Returns whether a value is a currently valid signed continuation.
+ *
+ * @internal
+ */
+export declare function hasValidCodeModeContinuationCapability(value: unknown): value is CodeModeContinuation;
+//# sourceMappingURL=continuation-capability.d.ts.map