Streaming output and webhook-based completion when run in workflow

[pranaygp]

Summary

Example app and SDK improvements that showcase @vercel/sandbox + Workflow DevKit integration:

• Webhook-based command completion: Detached runCommand automatically creates a workflow webhook and wraps the command in a shell script that POSTs the exit code when done. cmd.wait() suspends the workflow until the webhook fires — no step is blocked polling, and we're not bound by serverless function timeouts while waiting for long-running sandbox processes.

• Live streaming stdout/stderr: Sandbox command output is piped to workflow named streams (getWritable), which the client reads via SSE in real-time.

• writeFiles accepts strings: Buffer isn't available in the workflow VM, so writeFiles now accepts string | Buffer for content, converting inside the step where Node.js APIs are available.

• runCommand accepts Web WritableStream: In addition to Node.js Writable, enabling direct use of workflow's getWritable() streams.

How it works

export async function runCode(prompt: string) {
  "use workflow";

  const sandbox = await Sandbox.create({ runtime: "node24" });

  // Workflow named streams — client reads via run.getReadable()
  const stdout = getWritable<string>({ namespace: "stdout" });
  const stderr = getWritable<string>({ namespace: "stderr" });

  await sandbox.writeFiles([{ path: "script.js", content: code }]);

  // runCommand automatically creates a workflow webhook in workflow context.
  // The command is wrapped: `node script.js; curl -X POST webhook_url -d '{"exitCode":$?}'`
  const cmd = await sandbox.runCommand({
    cmd: "node",
    args: ["script.js"],
    stdout, // Web WritableStream from workflow — piped inside the step
    stderr,
    detached: true,
  });

  // Workflow suspends here. No step is blocked polling.
  // When the sandbox command finishes, it POSTs to the webhook,
  // and the workflow resumes with the exit code.
  const finished = await cmd.wait();

  await sandbox.stop();
}

SDK changes

Change	File
writeFiles accepts string | Buffer content	sandbox.ts
runCommand stdout/stderr accept Writable | WritableStream	sandbox.ts
runCommand with detached: true auto-creates workflow webhook	sandbox.ts
cmd.wait() uses webhook in workflow context, falls back to polling	command.ts
Webhook included in WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE	command.ts
ensureClient() called before logs() in getCachedOutput	command.ts
"workflow" marked as external in tsdown config	tsdown.config.ts

Example app

Multi-runtime (Node.js 24/22, Python 3.13, Bash) code runner with:

• AI code generation + auto-retry on failure (up to 3 attempts)
• Live streaming output via SSE
• Split-pane UI: syntax-highlighted code (shiki) + terminal output
• Real-time status updates (creating sandbox, generating, running, etc.)

Test plan

• All 116 SDK unit tests pass
• Build and typecheck pass
• Run the example app locally and verify workflow completes with streaming output
• Test with each runtime (Node.js, Python, Bash)
• Verify webhook-based completion works on Vercel deployment (check workflow observability — should show webhook suspension, not _waitStep)

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
sandbox	Error		Apr 2, 2026 6:47pm
sandbox-cli	Ready	Preview, Comment	Apr 2, 2026 6:47pm
sandbox-sdk	Ready	Preview, Comment	Apr 2, 2026 6:47pm
sandbox-sdk-ai-example	Ready	Preview, Comment	Apr 2, 2026 6:47pm
workflow-code-runner	Error		Apr 2, 2026 6:47pm

[pranaygp]

this part seem hacky and needs review - not sure how safe this is in production where we're wrapping all sorts of arbitrary user code/programs

[pranaygp]

for demo only - need to switch back to main before publishing. It's not required to work but just testing a perf improvement in workflow

[vercel]

WritableStream writer is never released after pipeLogs completes, causing TypeError when the same stream is reused across multiple runCommand calls.

[Copilot]

Pull request overview

This PR enhances @vercel/sandbox’s Workflow DevKit integration by enabling webhook-based completion for detached commands and live stdout/stderr streaming into workflow named streams, plus updates the workflow code-runner example to demonstrate multi-runtime execution with real-time UI output.

Changes:

• SDK: runCommand({ detached: true }) attempts to create a workflow webhook and Command.wait() can suspend on webhook completion; runCommand stdout/stderr now accept Node Writable or Web WritableStream; writeFiles now accepts string | Buffer.
• SDK: Command serialization/deserialization includes the webhook primitive; getCachedOutput() ensures the client is initialized before streaming logs.
• Example app: adds SSE streaming for stdout/stderr/status, multi-runtime runner (Node 24/22, Python 3.13, Bash), and a split-pane UI with syntax highlighting + ANSI terminal rendering.

Reviewed changes

Copilot reviewed 15 out of 16 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
pnpm-lock.yaml	Adds example dependencies (shiki, ansi-to-react) and switches workflow to a tarball URL.
packages/vercel-sandbox/tsdown.config.ts	Marks workflow as external to avoid bundling an optional runtime import.
packages/vercel-sandbox/src/sandbox.ts	Adds webhook wiring for detached commands, Web WritableStream support for log piping, and writeFiles string support.
packages/vercel-sandbox/src/command.ts	Adds webhook field to serialization and webhook-based wait() path; ensures client before logs() usage in cached output.
examples/workflow-code-runner/workflows/code-runner.ts	Reworks workflow to use Sandbox directly, add multi-runtime support, named stream piping, and webhook-based detached execution.
examples/workflow-code-runner/steps/status.ts	Adds a workflow step to emit structured status updates to a named stream.
examples/workflow-code-runner/steps/sandbox.ts	Removes old sandbox helper steps (now handled inline in the workflow).
examples/workflow-code-runner/steps/ai.ts	Updates AI steps to generate/fix code for a selected language/runtime.
examples/workflow-code-runner/package.json	Adds shiki, ansi-to-react, and switches workflow dependency to a tarball URL.
examples/workflow-code-runner/app/page.tsx	Updates UI to multi-runtime input + split panes and consumes SSE streams for live output/status.
examples/workflow-code-runner/app/globals.css	Adds theme variables and Shiki line-number styling.
examples/workflow-code-runner/app/components/terminal.tsx	Adds ANSI-rendering terminal component with autoscroll.
examples/workflow-code-runner/app/components/code-block.tsx	Adds Shiki-based syntax-highlighted code block with fallback rendering.
examples/workflow-code-runner/app/api/run/route.ts	Adds SSE streaming endpoints for stdout/stderr/status and keeps polling endpoint for completion.
examples/workflow-code-runner/NOTES.md	Documents known limitations for local webhook resumption and preview protection.
examples/workflow-code-runner/.gitignore	Expands ignores for local Vercel and env files (one path needs correction).

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

These EventSource connections are only closed on the “completed/failed” poll paths. If polling throws (network/JSON error) or the handler exits early, the SSE connections can remain open and leak. Consider storing the sources in refs and closing them in the catch path and/or via an effect cleanup on unmount.

[Copilot]

For Web WritableStreams, writer.write() is async and can apply backpressure / reject; currently pipeLogs() doesn’t await writes, so failures/backpressure are ignored and may surface as unhandled rejections or memory growth. Consider awaiting Web writes and releasing the writer lock in finally (and/or aborting the stream on error).

[Copilot]

This .gitignore entry likely won’t match because it’s already inside examples/workflow-code-runner/; examples/workflow-code-runner/public/.well-known/ is an extra path prefix. Use a path relative to this directory (e.g. public/.well-known/ or /public/.well-known/) so the well-known folder is actually ignored.

Suggested change

	examples/workflow-code-runner/public/.well-known/
	/public/.well-known/

[Copilot]

setTimeout(pollResult, 1000) isn’t tracked/cleared. If the component unmounts or a new run starts, this can still fire and set state on an unmounted component / race with the next run. Consider storing the timeout id and clearing it in cleanup/unmount.

[Copilot]

Unused import: createWebhook is imported but never referenced in this workflow. If it’s no longer needed now that the SDK handles webhook creation internally, remove it to avoid confusion and keep the example minimal.

Suggested change

	import { createWebhook, getWritable } from "workflow";
	import { getWritable } from "workflow";

[Copilot]

This introduces a webhook-based completion branch in wait(), but there’s no unit coverage for the webhook path (payload parsing/validation, abort behavior). Adding a small unit test for the _webhook branch would help prevent regressions between workflow and non-workflow contexts.

[Copilot]

The _onCompleteUrl path changes the executed command to sh -c ... and relies on the webhook URL being wired through correctly, but there’s no unit test asserting the wrapped command/args. Consider adding a unit test around this branch to lock in the behavior and avoid regressions.

[Copilot]

Detached log piping errors are only forwarded via .emit('error') when the provided stream is a Node Writable. If callers pass a Web WritableStream, errors are silently dropped. Consider detecting Web streams and signaling errors via writer.abort(err) (or another explicit error channel).

Suggested change

	if (errStream && "emit" in errStream) {
	errStream.emit("error", err);
	if (errStream && typeof (errStream as any).emit === "function") {
	(errStream as any).emit("error", err);
	} else if (errStream && typeof (errStream as any).getWriter === "function") {
	// Support Web WritableStream: forward error via writer.abort(err)
	try {
	const writer = (errStream as any).getWriter();
	void writer.abort(err).catch(() => {
	// Ignore abort errors to avoid unhandled rejections
	});
	} catch {
	// Ignore failures obtaining writer or aborting
	}

[Copilot]

Webhook completion wraps the command with sh -c and uses curl to POST the exit code. The sandbox README’s system section doesn’t document curl as available, so this may be brittle across images/runtimes and could leave workflows hanging if curl is missing. Consider using a more guaranteed mechanism (e.g. Node runtime fetch) or documenting/ensuring curl availability.

Suggested change

	cmd = "sh";
	cmdArgs = [
	"-c",
	`${escaped}; EXIT_CODE=$?; curl -s -X POST -H 'Content-Type: application/json' -d "{\\"exitCode\\":$EXIT_CODE}" '${params._onCompleteUrl}'; exit $EXIT_CODE`,
	const onCompleteUrlEscaped = params._onCompleteUrl.replace(/'/g, "'\\''");
	cmd = "sh";
	cmdArgs = [
	"-c",
	`${escaped}; EXIT_CODE=$?; HOOK_URL='${onCompleteUrlEscaped}'; PAYLOAD="{\\"exitCode\\":$EXIT_CODE}"; if command -v curl >/dev/null 2>&1; then curl -s -X POST -H 'Content-Type: application/json' -d "$PAYLOAD" "$HOOK_URL" >/dev/null 2>&1 || true; elif command -v node >/dev/null 2>&1; then node -e "const url=process.argv[2];const body=process.argv[3];(async()=>{try{await fetch(url,{method:'POST',headers:{'Content-Type':'application/json'},body});}catch(e){}})();" "$HOOK_URL" "$PAYLOAD" >/dev/null 2>&1 || true; fi; exit $EXIT_CODE`,

[Copilot]

updateStatus() should release the writer lock even if writer.write() throws/rejects; currently releaseLock() won’t run on errors and the stream can remain permanently locked. Wrap the write in try/finally (and consider reusing a writer if this is called frequently).

Suggested change

	await writer.write(JSON.stringify({ phase, attempt, code }));
	writer.releaseLock();
	try {
	await writer.write(JSON.stringify({ phase, attempt, code }));
	} finally {
	writer.releaseLock();
	}

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​shiki@​4.0.2
	npm/​ansi-to-react@​6.2.6

View full report