From 3005e600d254a7572bc11d6fecc63bbb5a50a7a4 Mon Sep 17 00:00:00 2001 From: Mohammad Garmabi <49670466+mohamadgarmabi@users.noreply.github.com> Date: Mon, 16 Nov 2026 10:22:09 +0330 Subject: [PATCH 1/5] fix(ai-sandbox-local-process): decode exec() output across chunks --- packages/ai-sandbox-local-process/src/handle.ts | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/packages/ai-sandbox-local-process/src/handle.ts b/packages/ai-sandbox-local-process/src/handle.ts index 9c556d5d6f..b8bfe453fa 100644 --- a/packages/ai-sandbox-local-process/src/handle.ts +++ b/packages/ai-sandbox-local-process/src/handle.ts @@ -886,8 +886,10 @@ export class LocalProcessHandle implements SandboxHandle { this.track(child) let stdout = '' let stderr = '' - child.stdout.on('data', (d: Buffer) => (stdout += d.toString('utf8'))) - child.stderr.on('data', (d: Buffer) => (stderr += d.toString('utf8'))) + // setEncoding decodes across chunks, so a multi-byte character split + // between two `data` events is not turned into U+FFFD (see decodeStream). + child.stdout.setEncoding('utf8').on('data', (d: string) => (stdout += d)) + child.stderr.setEncoding('utf8').on('data', (d: string) => (stderr += d)) const onAbort = (): void => { killTree(child, undefined, this.options.logger) } From 0181ec0ef5d29edf19d68927ef73f30d69e3dd67 Mon Sep 17 00:00:00 2001 From: Mohammad Garmabi <49670466+mohamadgarmabi@users.noreply.github.com> Date: Mon, 16 Nov 2026 10:22:38 +0330 Subject: [PATCH 2/5] test(ai-sandbox-local-process): cover exec() split UTF-8 output --- .../tests/local-process.test.ts | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/packages/ai-sandbox-local-process/tests/local-process.test.ts b/packages/ai-sandbox-local-process/tests/local-process.test.ts index 9b59b04fff..0bf845a96d 100644 --- a/packages/ai-sandbox-local-process/tests/local-process.test.ts +++ b/packages/ai-sandbox-local-process/tests/local-process.test.ts @@ -393,6 +393,28 @@ describe('local-process spawn stdout — UTF-8 decoding', () => { await sbx.destroy() }) + it('exec() reassembles a multi-byte character split across chunk boundaries', async () => { + const sbx = await fresh() + await sbx.fs.write( + '/workspace/split-utf8.mjs', + [ + `const euro = Buffer.from('€', 'utf8')`, + `process.stdout.write(euro.subarray(0, 1))`, + `process.stderr.write(euro.subarray(0, 1))`, + `setTimeout(() => {`, + ` process.stdout.write(euro.subarray(1))`, + ` process.stderr.write(euro.subarray(1))`, + `}, 50)`, + ].join('\n'), + ) + const result = await sbx.process.exec('node split-utf8.mjs', { + cwd: '/workspace', + }) + expect(result.stdout).toBe('€') + expect(result.stderr).toBe('€') + await sbx.destroy() + }) + it('flushes a genuinely truncated trailing sequence at end of stream (as U+FFFD, not silently dropped)', async () => { const sbx = await fresh() await sbx.fs.write( From f843c1c7eb2c7dcd43733651b16646d3332559cb Mon Sep 17 00:00:00 2001 From: Mohammad Garmabi <49670466+mohamadgarmabi@users.noreply.github.com> Date: Mon, 16 Nov 2026 10:22:58 +0330 Subject: [PATCH 3/5] chore: add changeset for exec() UTF-8 fix --- .changeset/local-process-exec-utf8.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/local-process-exec-utf8.md diff --git a/.changeset/local-process-exec-utf8.md b/.changeset/local-process-exec-utf8.md new file mode 100644 index 0000000000..51e3460619 --- /dev/null +++ b/.changeset/local-process-exec-utf8.md @@ -0,0 +1,5 @@ +--- +'@tanstack/ai-sandbox-local-process': patch +--- + +`exec()` no longer corrupts multi-byte UTF-8 characters in `stdout` and `stderr`. A character that a pipe split across two reads used to decode as U+FFFD. Output is now decoded across chunks, like `spawn()` already does. From ec6611537b2a281a657b07fcadd0917665ef4ca7 Mon Sep 17 00:00:00 2001 From: "m.garmabi" Date: Tue, 17 Nov 2026 09:46:21 +0330 Subject: [PATCH 4/5] test(e2e): cover local-process exec() UTF-8 split across chunks Add an E2E route and spec that run a command through the local-process sandbox's exec(). The command writes one byte at a time to stdout and stderr, so each multi-byte character is split between data chunks. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01EPthKYoTrYAFYTsJwhyaYE --- testing/e2e/src/routeTree.gen.ts | 22 ++++++++ .../routes/api.sandbox-local-process-exec.ts | 50 +++++++++++++++++++ .../tests/sandbox-local-process-exec.spec.ts | 37 ++++++++++++++ 3 files changed, 109 insertions(+) create mode 100644 testing/e2e/src/routes/api.sandbox-local-process-exec.ts create mode 100644 testing/e2e/tests/sandbox-local-process-exec.spec.ts diff --git a/testing/e2e/src/routeTree.gen.ts b/testing/e2e/src/routeTree.gen.ts index d29c9cb3e7..e2fdaa27a8 100644 --- a/testing/e2e/src/routeTree.gen.ts +++ b/testing/e2e/src/routeTree.gen.ts @@ -196,6 +196,7 @@ import { Route as ApiResponsesAnswerItemsWireRouteImport } from './routes/api.re import { Route as ApiRetryAfterRouteImport } from './routes/api.retry-after' import { Route as ApiSandboxDurabilityRouteImport } from './routes/api.sandbox-durability' import { Route as ApiSandboxFilePersistenceRouteImport } from './routes/api.sandbox-file-persistence' +import { Route as ApiSandboxLocalProcessExecRouteImport } from './routes/api.sandbox-local-process-exec' import { Route as ApiSandboxToolHistoryRouteImport } from './routes/api.sandbox-tool-history' import { Route as ApiServerToolStoreWireRouteImport } from './routes/api.server-tool-store-wire' import { Route as ApiStructuredOutputLengthWireRouteImport } from './routes/api.structured-output-length-wire' @@ -1210,6 +1211,12 @@ const ApiSandboxFilePersistenceRoute = path: '/api/sandbox-file-persistence', getParentRoute: () => rootRouteImport, } as any) +const ApiSandboxLocalProcessExecRoute = + ApiSandboxLocalProcessExecRouteImport.update({ + id: '/api/sandbox-local-process-exec', + path: '/api/sandbox-local-process-exec', + getParentRoute: () => rootRouteImport, + } as any) const ApiSandboxToolHistoryRoute = ApiSandboxToolHistoryRouteImport.update({ id: '/api/sandbox-tool-history', path: '/api/sandbox-tool-history', @@ -1547,6 +1554,7 @@ export interface FileRoutesByFullPath { '/api/retry-after': typeof ApiRetryAfterRoute '/api/sandbox-durability': typeof ApiSandboxDurabilityRoute '/api/sandbox-file-persistence': typeof ApiSandboxFilePersistenceRoute + '/api/sandbox-local-process-exec': typeof ApiSandboxLocalProcessExecRoute '/api/sandbox-tool-history': typeof ApiSandboxToolHistoryRoute '/api/server-tool-store-wire': typeof ApiServerToolStoreWireRoute '/api/structured-output-length-wire': typeof ApiStructuredOutputLengthWireRoute @@ -1765,6 +1773,7 @@ export interface FileRoutesByTo { '/api/retry-after': typeof ApiRetryAfterRoute '/api/sandbox-durability': typeof ApiSandboxDurabilityRoute '/api/sandbox-file-persistence': typeof ApiSandboxFilePersistenceRoute + '/api/sandbox-local-process-exec': typeof ApiSandboxLocalProcessExecRoute '/api/sandbox-tool-history': typeof ApiSandboxToolHistoryRoute '/api/server-tool-store-wire': typeof ApiServerToolStoreWireRoute '/api/structured-output-length-wire': typeof ApiStructuredOutputLengthWireRoute @@ -1984,6 +1993,7 @@ export interface FileRoutesById { '/api/retry-after': typeof ApiRetryAfterRoute '/api/sandbox-durability': typeof ApiSandboxDurabilityRoute '/api/sandbox-file-persistence': typeof ApiSandboxFilePersistenceRoute + '/api/sandbox-local-process-exec': typeof ApiSandboxLocalProcessExecRoute '/api/sandbox-tool-history': typeof ApiSandboxToolHistoryRoute '/api/server-tool-store-wire': typeof ApiServerToolStoreWireRoute '/api/structured-output-length-wire': typeof ApiStructuredOutputLengthWireRoute @@ -2204,6 +2214,7 @@ export interface FileRouteTypes { | '/api/retry-after' | '/api/sandbox-durability' | '/api/sandbox-file-persistence' + | '/api/sandbox-local-process-exec' | '/api/sandbox-tool-history' | '/api/server-tool-store-wire' | '/api/structured-output-length-wire' @@ -2422,6 +2433,7 @@ export interface FileRouteTypes { | '/api/retry-after' | '/api/sandbox-durability' | '/api/sandbox-file-persistence' + | '/api/sandbox-local-process-exec' | '/api/sandbox-tool-history' | '/api/server-tool-store-wire' | '/api/structured-output-length-wire' @@ -2640,6 +2652,7 @@ export interface FileRouteTypes { | '/api/retry-after' | '/api/sandbox-durability' | '/api/sandbox-file-persistence' + | '/api/sandbox-local-process-exec' | '/api/sandbox-tool-history' | '/api/server-tool-store-wire' | '/api/structured-output-length-wire' @@ -2859,6 +2872,7 @@ export interface RootRouteChildren { ApiRetryAfterRoute: typeof ApiRetryAfterRoute ApiSandboxDurabilityRoute: typeof ApiSandboxDurabilityRoute ApiSandboxFilePersistenceRoute: typeof ApiSandboxFilePersistenceRoute + ApiSandboxLocalProcessExecRoute: typeof ApiSandboxLocalProcessExecRoute ApiSandboxToolHistoryRoute: typeof ApiSandboxToolHistoryRoute ApiServerToolStoreWireRoute: typeof ApiServerToolStoreWireRoute ApiStructuredOutputLengthWireRoute: typeof ApiStructuredOutputLengthWireRoute @@ -4197,6 +4211,13 @@ declare module '@tanstack/react-router' { preLoaderRoute: typeof ApiSandboxFilePersistenceRouteImport parentRoute: typeof rootRouteImport } + '/api/sandbox-local-process-exec': { + id: '/api/sandbox-local-process-exec' + path: '/api/sandbox-local-process-exec' + fullPath: '/api/sandbox-local-process-exec' + preLoaderRoute: typeof ApiSandboxLocalProcessExecRouteImport + parentRoute: typeof rootRouteImport + } '/api/sandbox-tool-history': { id: '/api/sandbox-tool-history' path: '/api/sandbox-tool-history' @@ -4654,6 +4675,7 @@ const rootRouteChildren: RootRouteChildren = { ApiRetryAfterRoute: ApiRetryAfterRoute, ApiSandboxDurabilityRoute: ApiSandboxDurabilityRoute, ApiSandboxFilePersistenceRoute: ApiSandboxFilePersistenceRoute, + ApiSandboxLocalProcessExecRoute: ApiSandboxLocalProcessExecRoute, ApiSandboxToolHistoryRoute: ApiSandboxToolHistoryRoute, ApiServerToolStoreWireRoute: ApiServerToolStoreWireRoute, ApiStructuredOutputLengthWireRoute: ApiStructuredOutputLengthWireRoute, diff --git a/testing/e2e/src/routes/api.sandbox-local-process-exec.ts b/testing/e2e/src/routes/api.sandbox-local-process-exec.ts new file mode 100644 index 0000000000..01b2ab3925 --- /dev/null +++ b/testing/e2e/src/routes/api.sandbox-local-process-exec.ts @@ -0,0 +1,50 @@ +import { createFileRoute } from '@tanstack/react-router' +import { localProcessSandbox } from '@tanstack/ai-sandbox-local-process' + +/** + * `exec()` of the local-process sandbox, with output that has multi-byte + * characters. Body: `{ root }`, a folder in the temp folder that the test + * made. The answer is the JSON of the exec result. + * + * The script writes each byte of `TEXT` by itself, with a pause between the + * writes, to stdout and to stderr. So each multi-byte character comes to the + * sandbox in more than one `data` chunk, and `exec()` must decode across the + * chunks to give back `TEXT`, not U+FFFD. + */ + +/** Two, three and four byte UTF-8 characters, and Persian text. */ +export const TEXT = 'é € 😀 سلام' + +const SCRIPT = [ + `const bytes = Buffer.from(${JSON.stringify(TEXT)}, 'utf8')`, + `let index = 0`, + `const next = () => {`, + ` if (index >= bytes.length) return`, + ` const byte = bytes.subarray(index, index + 1)`, + ` process.stdout.write(byte)`, + ` process.stderr.write(byte)`, + ` index += 1`, + ` setTimeout(next, 5)`, + `}`, + `next()`, +].join('\n') + +export const Route = createFileRoute('/api/sandbox-local-process-exec')({ + server: { + handlers: { + POST: async ({ request }) => { + const { root } = (await request.json()) as { root: string } + const sandbox = await localProcessSandbox({ dir: root }).create({}) + try { + await sandbox.fs.write('/workspace/split-utf8.mjs', SCRIPT) + const result = await sandbox.process.exec('node split-utf8.mjs', { + cwd: '/workspace', + }) + return Response.json(result) + } finally { + await sandbox.destroy() + } + }, + }, + }, +}) diff --git a/testing/e2e/tests/sandbox-local-process-exec.spec.ts b/testing/e2e/tests/sandbox-local-process-exec.spec.ts new file mode 100644 index 0000000000..6b0fcf285c --- /dev/null +++ b/testing/e2e/tests/sandbox-local-process-exec.spec.ts @@ -0,0 +1,37 @@ +import { mkdtemp, rm } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { expect, test } from '@playwright/test' +import { TEXT } from '../src/routes/api.sandbox-local-process-exec' + +/** + * `exec()` of the local-process sandbox decodes UTF-8 across output chunks. + * The route runs a command that writes one byte at a time, so each + * multi-byte character is split between `data` chunks. + */ +test.describe('local-process sandbox exec() output', () => { + let root = '' + + test.beforeEach(async () => { + root = await mkdtemp(join(tmpdir(), 'e2e-local-process-exec-')) + }) + + test.afterEach(async () => { + await rm(root, { recursive: true, force: true }) + }) + + test('keeps multi-byte characters split across chunks', async ({ + request, + }) => { + const response = await request.post('/api/sandbox-local-process-exec', { + data: { root }, + }) + const body = await response.text() + expect(response.ok(), body).toBe(true) + + const result = JSON.parse(body) + expect(result).toEqual({ stdout: TEXT, stderr: TEXT, exitCode: 0 }) + expect(result.stdout).not.toContain('�') + expect(result.stderr).not.toContain('�') + }) +}) From aa13cdfe1f78bc7b66a705579c403b165478ee24 Mon Sep 17 00:00:00 2001 From: Tom Beckenham <34339192+tombeckenham@users.noreply.github.com> Date: Sat, 21 Nov 2026 13:57:35 +1100 Subject: [PATCH 5/5] Fix: guard the e2e exec route's root folder Reject a root outside the temp folder with 400, like api.coding-tools.ts, and add a spec case for it. Drop two not.toContain assertions that the toEqual above already implies. --- .../src/routes/api.sandbox-local-process-exec.ts | 14 +++++++++++++- .../e2e/tests/sandbox-local-process-exec.spec.ts | 9 +++++++-- 2 files changed, 20 insertions(+), 3 deletions(-) diff --git a/testing/e2e/src/routes/api.sandbox-local-process-exec.ts b/testing/e2e/src/routes/api.sandbox-local-process-exec.ts index 01b2ab3925..a05a113e9e 100644 --- a/testing/e2e/src/routes/api.sandbox-local-process-exec.ts +++ b/testing/e2e/src/routes/api.sandbox-local-process-exec.ts @@ -1,3 +1,5 @@ +import { tmpdir } from 'node:os' +import { resolve, sep } from 'node:path' import { createFileRoute } from '@tanstack/react-router' import { localProcessSandbox } from '@tanstack/ai-sandbox-local-process' @@ -33,7 +35,17 @@ export const Route = createFileRoute('/api/sandbox-local-process-exec')({ server: { handlers: { POST: async ({ request }) => { - const { root } = (await request.json()) as { root: string } + const body: unknown = await request.json() + const rootField = + typeof body === 'object' && body !== null && 'root' in body + ? body.root + : undefined + const root = typeof rootField === 'string' ? resolve(rootField) : '' + if (!root.startsWith(resolve(tmpdir()) + sep)) { + return new Response('root must be in the temp folder', { + status: 400, + }) + } const sandbox = await localProcessSandbox({ dir: root }).create({}) try { await sandbox.fs.write('/workspace/split-utf8.mjs', SCRIPT) diff --git a/testing/e2e/tests/sandbox-local-process-exec.spec.ts b/testing/e2e/tests/sandbox-local-process-exec.spec.ts index 6b0fcf285c..b65ce75f13 100644 --- a/testing/e2e/tests/sandbox-local-process-exec.spec.ts +++ b/testing/e2e/tests/sandbox-local-process-exec.spec.ts @@ -31,7 +31,12 @@ test.describe('local-process sandbox exec() output', () => { const result = JSON.parse(body) expect(result).toEqual({ stdout: TEXT, stderr: TEXT, exitCode: 0 }) - expect(result.stdout).not.toContain('�') - expect(result.stderr).not.toContain('�') + }) + + test('rejects a root outside the temp folder', async ({ request }) => { + const response = await request.post('/api/sandbox-local-process-exec', { + data: { root: '/' }, + }) + expect(response.status()).toBe(400) }) })