fix(ai-sandbox): address Blaxel review feedback

Author: SystemSculpt

packages/ai-sandbox-blaxel/src/handle.ts

@@ -53,8 +53,16 @@ export const BLAXEL_CAPS: SandboxCapabilities = {
 /** Default workspace root created inside the sandbox. */
 export const BLAXEL_DEFAULT_WORKDIR = '/workspace'
 
-/** How long a minted preview token stays valid. */
+/** Fallback when a preview TTL uses an unknown server-side duration format. */
 const PREVIEW_TOKEN_TTL_MS = 60 * 60 * 1000
+const PREVIEW_TTL_UNIT_MS: Record<string, number> = {
+  ms: 1,
+  s: 1000,
+  m: 60 * 1000,
+  h: 60 * 60 * 1000,
+  d: 24 * 60 * 60 * 1000,
+  w: 7 * 24 * 60 * 60 * 1000,
+}
 
 /** Maximum unread stdout or stderr retained per spawned process. */
 const STREAM_BUFFER_LIMIT_BYTES = 8 * 1024 * 1024
@@ -139,7 +147,7 @@ export interface BlaxelProcessLike {
 }
 
 export interface BlaxelPreviewLike {
-  spec?: { url?: string; public?: boolean; port?: number }
+  spec?: { url?: string; public?: boolean; port?: number; expires?: string }
   tokens: { create: (expiresAt: Date) => Promise<{ value: string }> }
 }
 
@@ -161,6 +169,37 @@ export interface BlaxelHandleDeps {
   previewTtl: string
 }
 
+function previewTtlMilliseconds(ttl: string): number {
+  let milliseconds = 0
+  let offset = 0
+  for (const match of ttl.matchAll(/(\d+(?:\.\d+)?)(ms|s|m|h|d|w)/g)) {
+    if (match.index !== offset) return PREVIEW_TOKEN_TTL_MS
+    const amount = match[1]
+    const unitMilliseconds = PREVIEW_TTL_UNIT_MS[match[2] ?? '']
+    if (amount === undefined || unitMilliseconds === undefined) {
+      return PREVIEW_TOKEN_TTL_MS
+    }
+    milliseconds += Number(amount) * unitMilliseconds
+    offset += match[0].length
+  }
+  return offset === ttl.length &&
+    milliseconds > 0 &&
+    Number.isFinite(milliseconds)
+    ? milliseconds
+    : PREVIEW_TOKEN_TTL_MS
+}
+
+function previewTokenExpiresAt(
+  preview: BlaxelPreviewLike,
+  previewTtl: string,
+): Date {
+  if (preview.spec?.expires) {
+    const serverExpiry = new Date(preview.spec.expires)
+    if (Number.isFinite(serverExpiry.getTime())) return serverExpiry
+  }
+  return new Date(Date.now() + previewTtlMilliseconds(previewTtl))
+}
+
 export class BlaxelHandle implements SandboxHandle {
   readonly id: string
   readonly provider = 'blaxel'
@@ -382,7 +421,7 @@ export class BlaxelHandle implements SandboxHandle {
         `  cat ${chunkFile} >> ${file} || { __tanstack_capture_status=1; break; }`,
         `  printf '%s' ${q(recordPrefix)}`,
         `  base64 < ${chunkFile} | tr -d '\r\n'`,
-        `  printf '\n'`,
+        `  printf '\\n'`,
         '  __tanstack_remaining=$((__tanstack_remaining - __tanstack_chunk_size))',
         'done',
         'if [ "$__tanstack_capture_status" -eq 0 ] && [ "$__tanstack_remaining" -eq 0 ]; then',
@@ -395,8 +434,8 @@ export class BlaxelHandle implements SandboxHandle {
         'fi',
         `rm -f -- ${chunkFile}`,
         'if [ "$__tanstack_capture_status" -ne 0 ]; then',
-        `  printf '%s\n' ${q(label)} >> ${limitsFile}`,
-        `  printf '%s\n' ${q(overflowMarker)}`,
+        `  printf '%s\\n' ${q(label)} >> ${limitsFile}`,
+        `  printf '%s\\n' ${q(overflowMarker)}`,
         'fi',
         `) < ${pipe}${redirect} &`,
       ].join('\n')
@@ -954,7 +993,7 @@ export class BlaxelHandle implements SandboxHandle {
     // Keep the credential out of the URL and report Blaxel's explicit preview
     // header. The separate token field remains available to channel consumers.
     const token = await preview.tokens.create(
-      new Date(Date.now() + PREVIEW_TOKEN_TTL_MS),
+      previewTokenExpiresAt(preview, this.previewTtl),
     )
     if (!token.value) {
       throw new Error(

packages/ai-sandbox-blaxel/tests/blaxel.test.ts

@@ -153,7 +153,7 @@ describe.skipIf(gated)(
       // survives in a terminal state — so resume() has to read the status.
       // Without that check this returns a handle to a dead sandbox.
       const provider = blaxelSandbox({ apiKey, workspace })
-      const sbx = await provider.create({})
+      const sbx = track(await provider.create({}))
       await sbx.destroy()
       expect(await provider.resume({ id: sbx.id })).toBeNull()
     }, 180_000)

packages/ai-sandbox-blaxel/tests/handle.test.ts

@@ -1,7 +1,7 @@
 /* eslint-disable @typescript-eslint/require-await -- trivial fixed-value fakes */
 import { SandboxInstance } from '@blaxel/core'
 import { toLines } from '@tanstack/ai-sandbox'
-import { spawn as spawnChild } from 'node:child_process'
+import { spawn as spawnChild, spawnSync } from 'node:child_process'
 import { existsSync, readFileSync, rmSync } from 'node:fs'
 import { describe, expect, it, vi } from 'vitest'
 import { BLAXEL_CAPS, BlaxelHandle, previewName } from '../src/handle'
@@ -23,6 +23,7 @@ interface FakeOptions {
   previewUrl?: string | undefined
   previewPublic?: boolean
   previewPort?: number
+  previewExpires?: string
   watchBase?: string
   waitResult?: BlaxelProcessLike
   waitGate?: Promise<BlaxelProcessLike>
@@ -178,6 +179,9 @@ function fakeSandbox(options: FakeOptions = {}): {
               : { url: 'https://abc.preview.bl.run' }),
             public: options.previewPublic ?? preview.spec.public,
             port: options.previewPort ?? preview.spec.port,
+            ...(options.previewExpires
+              ? { expires: options.previewExpires }
+              : {}),
           },
           tokens: { create: tokenCreate },
         }
@@ -204,6 +208,7 @@ function makeHandle(
   overrides: {
     workdir?: string
     publicPreviews?: boolean
+    previewTtl?: string
   } = {},
 ): {
   handle: BlaxelHandle
@@ -215,7 +220,7 @@ function makeHandle(
     name: 'sb',
     workdir: overrides.workdir ?? '/workspace',
     publicPreviews: overrides.publicPreviews ?? false,
-    previewTtl: '1h',
+    previewTtl: overrides.previewTtl ?? '1h',
   })
   return { handle, fake }
 }
@@ -683,7 +688,10 @@ describe('BlaxelHandle process', () => {
     expect(await collect(spawned.stderr)).toBe('warned')
   })
 
-  it.runIf(process.platform !== 'win32')(
+  it.runIf(
+    process.platform !== 'win32' &&
+      spawnSync('bash', ['-c', 'exit 0'], { stdio: 'ignore' }).status === 0,
+  )(
     'supervisor reaps the command and capture process groups on termination',
     async () => {
       let resolveWait!: (value: BlaxelProcessLike) => void
@@ -703,25 +711,35 @@ describe('BlaxelHandle process', () => {
       const child = spawnChild('/bin/sh', ['-c', script], {
         stdio: 'ignore',
       })
-      const pidsPath = `${outputDir!}/pids`
-      await vi.waitFor(() => expect(existsSync(pidsPath)).toBe(true))
-      const pids = readFileSync(pidsPath, 'utf8')
-        .trim()
-        .split(/\s+/)
-        .map(Number)
       const exited = new Promise<void>((resolve, reject) => {
         child.once('error', reject)
         child.once('exit', () => resolve())
       })
-      child.kill('SIGTERM')
-      await exited
-      await vi.waitFor(() => {
+      let pids: Array<number> = []
+      try {
+        const pidsPath = `${outputDir!}/pids`
+        await vi.waitFor(() => expect(existsSync(pidsPath)).toBe(true))
+        pids = readFileSync(pidsPath, 'utf8').trim().split(/\s+/).map(Number)
+        child.kill('SIGTERM')
+        await exited
+        await vi.waitFor(() => {
+          for (const pid of pids) {
+            expect(() => process.kill(-pid, 0)).toThrow()
+          }
+        })
+      } finally {
+        child.kill('SIGKILL')
         for (const pid of pids) {
-          expect(() => process.kill(-pid, 0)).toThrow()
+          try {
+            process.kill(-pid, 'SIGKILL')
+          } catch {
+            // The process group already exited.
+          }
         }
-      })
-      rmSync(outputDir!, { recursive: true, force: true })
-      resolveWait({ exitCode: 0, stdout: '', stderr: '' })
+        await exited.catch(() => undefined)
+        rmSync(outputDir!, { recursive: true, force: true })
+        resolveWait({ exitCode: 0, stdout: '', stderr: '' })
+      }
       await spawned.wait()
     },
   )
@@ -945,6 +963,25 @@ describe('BlaxelHandle ports', () => {
     })
   })
 
+  it('keeps a private preview token valid for a custom preview TTL', async () => {
+    const before = Date.now()
+    const { handle, fake } = makeHandle({}, { previewTtl: '4h' })
+    await handle.ports.connect(3000)
+    const after = Date.now()
+    const expiresAt = fake.tokenCreate.mock.calls[0]?.[0] as Date
+    expect(expiresAt.getTime()).toBeGreaterThanOrEqual(
+      before + 4 * 60 * 60 * 1000,
+    )
+    expect(expiresAt.getTime()).toBeLessThanOrEqual(after + 4 * 60 * 60 * 1000)
+  })
+
+  it('uses the preview expiration reported by Blaxel for its token', async () => {
+    const previewExpires = new Date(Date.now() + 90 * 60 * 1000).toISOString()
+    const { handle, fake } = makeHandle({ previewExpires })
+    await handle.ports.connect(3000)
+    expect(fake.tokenCreate).toHaveBeenCalledWith(new Date(previewExpires))
+  })
+
   it('returns a bare URL and mints no token for a public preview', async () => {
     const { handle, fake } = makeHandle({}, { publicPreviews: true })
     expect(await handle.ports.connect(8080)).toEqual({

packages/ai-sandbox-blaxel/tests/provider.test.ts

@@ -10,9 +10,9 @@ const calls: {
 
 let getError: unknown
 let getFactory: ((name: string) => Record<string, unknown>) | undefined
-let createGate: Promise<Record<string, unknown>> | undefined
+let createGate: (() => Promise<Record<string, unknown>>) | undefined
 let mkdirError: unknown
-let deleteGate: Promise<Record<string, never>> | undefined
+let deleteGate: (() => Promise<Record<string, never>>) | undefined
 
 let getStatus: string | undefined = 'DEPLOYED'
 
@@ -73,13 +73,12 @@ vi.mock('@blaxel/core', () => ({
   SandboxInstance: {
     createIfNotExists: async (config: Record<string, unknown>) => {
       calls.created.push(config)
-      return (
-        createGate ??
-        fakeInstance(
-          String(config.name),
-          config.labels as Record<string, string> | undefined,
-        )
-      )
+      return createGate
+        ? await createGate()
+        : fakeInstance(
+            String(config.name),
+            config.labels as Record<string, string> | undefined,
+          )
     },
     get: async (name: string) => {
       calls.got.push(name)
@@ -88,7 +87,7 @@ vi.mock('@blaxel/core', () => ({
     },
     delete: async (name: string) => {
       calls.deleted.push(name)
-      return deleteGate ?? {}
+      return deleteGate ? await deleteGate() : {}
     },
   },
 }))
@@ -244,9 +243,10 @@ describe('blaxelSandbox create', () => {
 
   it('aborts an in-flight create and deletes the late billed sandbox', async () => {
     let resolveCreate!: (sandbox: Record<string, unknown>) => void
-    createGate = new Promise((resolve) => {
-      resolveCreate = resolve
-    })
+    createGate = () =>
+      new Promise((resolve) => {
+        resolveCreate = resolve
+      })
     const controller = new AbortController()
     const provider = blaxelSandbox()
     const creating = provider.create({
@@ -266,7 +266,7 @@ describe('blaxelSandbox create', () => {
   })
 
   it('deletes an aborted create whose SDK promise never settles', async () => {
-    createGate = new Promise(() => undefined)
+    createGate = () => new Promise(() => undefined)
     let visible = false
     let visibilityScheduled = false
     getFactory = (name) => {
@@ -312,9 +312,12 @@ describe('blaxelSandbox create', () => {
 
   it('never deletes a same-name sandbox reused by concurrent callers', async () => {
     mkdirError = new Error('mkdir failed')
-    createGate = Promise.resolve(
-      fakeInstance('shared', { 'tanstack-ai-create-attempt': 'other-attempt' }),
-    )
+    createGate = () =>
+      Promise.resolve(
+        fakeInstance('shared', {
+          'tanstack-ai-create-attempt': 'other-attempt',
+        }),
+      )
     const provider = blaxelSandbox()
     const results = await Promise.allSettled([
       provider.create({ id: 'shared' }),
@@ -328,7 +331,8 @@ describe('blaxelSandbox create', () => {
   })
 
   it('reconciles and deletes an owned create accepted before a late 504', async () => {
-    createGate = Promise.reject({ status: 504, message: 'gateway timeout' })
+    createGate = () =>
+      Promise.reject({ status: 504, message: 'gateway timeout' })
     getFactory = (name) =>
       fakeInstance(
         name,
@@ -345,13 +349,14 @@ describe('blaxelSandbox create', () => {
   })
 
   it('reports cleanup failure after reconciling an accepted create error', async () => {
-    createGate = Promise.reject({ status: 504, message: 'gateway timeout' })
+    createGate = () =>
+      Promise.reject({ status: 504, message: 'gateway timeout' })
     getFactory = (name) =>
       fakeInstance(
         name,
         calls.created[0]?.labels as Record<string, string> | undefined,
       )
-    deleteGate = Promise.reject({ status: 500, message: 'delete failed' })
+    deleteGate = () => Promise.reject({ status: 500, message: 'delete failed' })
     const provider = blaxelSandbox()
     await expect(
       provider.create({ id: 'accepted-cleanup-failed' }),
@@ -361,7 +366,7 @@ describe('blaxelSandbox create', () => {
 
   it('reports both preparation and owned-sandbox cleanup failures', async () => {
     mkdirError = new Error('mkdir failed')
-    deleteGate = Promise.reject({ status: 500, message: 'delete failed' })
+    deleteGate = () => Promise.reject({ status: 500, message: 'delete failed' })
     const provider = blaxelSandbox()
     await expect(provider.create({ id: 'cleanup-failed' })).rejects.toThrow(
       /cleanup also failed|could not be cleaned up/,
@@ -443,13 +448,13 @@ describe('blaxelSandbox destroy', () => {
   })
 
   it('treats an already deleted sandbox as a successful destroy', async () => {
-    deleteGate = Promise.reject({ code: 404 })
+    deleteGate = () => Promise.reject({ code: 404 })
     const provider = blaxelSandbox()
     await expect(provider.destroy({ id: 'sb-gone' })).resolves.toBeUndefined()
   })
 
   it('does not hang past the destroy signal when the SDK call stalls', async () => {
-    deleteGate = new Promise(() => {})
+    deleteGate = () => new Promise(() => {})
     const controller = new AbortController()
     const provider = blaxelSandbox()
     const destroying = provider.destroy({

packages/ai-sandbox/README.md

@@ -55,6 +55,12 @@ Pick a **provider** package for where the sandbox runs:
 | `@tanstack/ai-sandbox-sprites`       | Sprites stateful sandboxes             |
 | `@tanstack/ai-sandbox-blaxel`        | Blaxel cloud sandboxes and previews    |
 
+Install the provider you select separately. For Blaxel:
+
+```bash
+npm install @tanstack/ai-sandbox-blaxel
+```
+
 **Harness adapters** are separate packages. The default path is **Grok Build** (`@tanstack/ai-grok-build`); others include `@tanstack/ai-claude-code`, `@tanstack/ai-codex`, and `@tanstack/ai-opencode`. All require `withSandbox(...)` middleware — `chat()` fails fast without it.
 
 ## Three moving parts