Make sandbox class work natively in workflow with "use step"

[TooTallNate]

Summary

Adds "use step" annotations to all API-calling async methods in the Sandbox SDK, building on the serialization support from #72. This allows Sandbox, Command, CommandFinished, and Snapshot instances to be used directly inside "use workflow" functions without needing manual step wrappers.

Changes

• Annotate all async API methods with "use step" in Sandbox, Command, CommandFinished, and Snapshot
• Simplify the workflow-code-runner example to call SDK methods directly in the workflow (removing the steps/sandbox.ts wrapper)

Before (manual step wrappers required)

// steps/sandbox.tsexportasyncfunctionexecute(sandbox: Sandbox,code: string){"use step";initCredentials();awaitsandbox.writeFiles([...]);constfinished=awaitsandbox.runCommand("node",["script.js"]);return{exitCode: finished.exitCode,stdout: awaitfinished.stdout(),stderr: awaitfinished.stderr()};}// workflows/code-runner.tsconstresult=awaitexecute(sandbox,code);

After (SDK methods are steps)

// workflows/code-runner.ts — no wrapper neededawaitsandbox.writeFiles([{path: "script.js",content: Buffer.from(code)}]);constfinished=awaitsandbox.runCommand("node",["script.js"]);conststdout=awaitfinished.stdout();

Test plan

• Verify workflow-code-runner example works end-to-end
• Confirm step replay correctly skips already-completed SDK calls

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
sandbox	Error		Mar 20, 2026 10:26pm
sandbox-cli	Ready	Preview, Comment	Mar 20, 2026 10:26pm
sandbox-sdk	Ready	Preview, Comment	Mar 20, 2026 10:26pm
sandbox-sdk-ai-example	Ready	Preview, Comment	Mar 20, 2026 10:26pm

[pranaygp]

Overall this is a solid approach to making Sandbox SDK classes workflow-serializable. The lazy client pattern via ensureClient() is clean, and the "use step" annotations are comprehensive. A few things worth addressing below.

[pranaygp]

Fragile: accessing parent private fields via (instance as any)

This duplicates the serialization logic from Command[WORKFLOW_SERIALIZE] and accesses sandboxId and cmd via as any casts because they are private on the parent class. If those field names are ever renamed, this will silently break.

Consider reusing the parent serializer:

static[WORKFLOW_SERIALIZE](instance: CommandFinished){return{
...Command[WORKFLOW_SERIALIZE](instance),exitCode: instance.exitCode,};}

This keeps CommandFinished serialization in sync with Command automatically.

[pranaygp]

Resolved — after rebasing onto #72, CommandFinished uses protected fields and accesses them directly in its serializer. No as any casts.

[pranaygp]

DisposableSandbox[WORKFLOW_DESERIALIZE] duplicates Sandbox[WORKFLOW_DESERIALIZE]

This is a near-copy of Sandbox[WORKFLOW_DESERIALIZE] — the only difference is the prototype used. Consider reusing the parent to avoid drift:

static[WORKFLOW_DESERIALIZE](data: {sandbox: ConvertedSandbox;
routes: SandboxRouteData[];
privateParams: Record<string,unknown>;}): DisposableSandbox{constinstance=Sandbox[WORKFLOW_DESERIALIZE](data);Object.setPrototypeOf(instance,DisposableSandbox.prototype);returninstanceasDisposableSandbox;}

[pranaygp]

Resolved — in #72's implementation, DisposableSandbox doesn't have its own WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE at all. No duplication.

[pranaygp]

Signal from concurrent callers is silently ignored

When stdout() and stderr() are called concurrently, only the signal from the first call is wired into getLogs(). The second caller's signal is ignored — it will wait for the first call to finish even if its own signal is aborted.

This was pre-existing behavior (the old code via this.logs() had the same issue), but worth noting now that this is explicitly step-compatible and more likely to be called in workflow contexts where cancellation semantics matter.

[pranaygp]

This is a pre-existing issue in the output caching logic from #72 — not introduced or changed by this PR (which only adds "use step" annotations). Leaving for a separate follow-up if needed.

[pranaygp]

nit: The error message says to use output(), stdout(), or stderr() instead — but these methods internally call getCachedOutput() which calls ensureClient() and then client.getLogs(). So the real distinction is that logs() requires a pre-existing client while the other methods can lazily reconstruct one. The error message is correct in its guidance but slightly misleading about why — it's not that logs() is inherently non-step-compatible, it's that it's synchronous and can't call the async ensureClient(). Maybe worth a small clarification:

"Cannot call logs() on a deserialized Command. " +
"logs() is synchronous and cannot lazily reconstruct the API client. " +
"Use output(), stdout(), or stderr() instead."

[pranaygp]

Resolved — in #72's implementation, logs() uses the lazy get client() getter which auto-creates the client from global credentials. There's no special error message for deserialized instances.

[pranaygp]

Minor: @workflow/serde is pinned to a beta pre-release (^4.1.0-beta.2). With the ^ range, this will accept any >=4.1.0-beta.2 <5.0.0 including future betas and the eventual stable release. Is that intentional? If the stable API is expected to be compatible, this is fine. If the beta API might still change, consider pinning more tightly (e.g., ~4.1.0-beta.2 or exact).

[pranaygp]

human: I think this is fine. we won't break serve in 4.x and we're going to 5.x soon on workflow

[pranaygp]

Resolved per above — staying with ^ range since serde won't break in 4.x.

[TooTallNate]

Superseded by #109, which re-implements this approach against the current tootallnate/serde branch with the additional fix of bundle: false in tsdown and the async ensureClient() pattern to keep APIClient out of the workflow bundle's module scope.

[TooTallNate]

Summary

Adds "use step" annotations to all API-calling async methods in the Sandbox SDK, building on the serialization support from #72. This allows Sandbox, Command, CommandFinished, and Snapshot instances to be used directly inside "use workflow" functions without needing manual step wrappers.

Changes

• Annotate all async API methods with "use step" in Sandbox, Command, CommandFinished, and Snapshot
• Simplify the workflow-code-runner example to call SDK methods directly in the workflow (removing the steps/sandbox.ts wrapper)

Before (manual step wrappers required)

// steps/sandbox.tsexportasyncfunctionexecute(sandbox: Sandbox,code: string){"use step";initCredentials();awaitsandbox.writeFiles([...]);constfinished=awaitsandbox.runCommand("node",["script.js"]);return{exitCode: finished.exitCode,stdout: awaitfinished.stdout(),stderr: awaitfinished.stderr()};}// workflows/code-runner.tsconstresult=awaitexecute(sandbox,code);

After (SDK methods are steps)

// workflows/code-runner.ts — no wrapper neededawaitsandbox.writeFiles([{path: "script.js",content: Buffer.from(code)}]);constfinished=awaitsandbox.runCommand("node",["script.js"]);conststdout=awaitfinished.stdout();

Test plan

• Verify workflow-code-runner example works end-to-end
• Confirm step replay correctly skips already-completed SDK calls

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
sandbox	Error		Mar 20, 2026 10:26pm
sandbox-cli	Ready	Preview, Comment	Mar 20, 2026 10:26pm
sandbox-sdk	Ready	Preview, Comment	Mar 20, 2026 10:26pm
sandbox-sdk-ai-example	Ready	Preview, Comment	Mar 20, 2026 10:26pm

[pranaygp]

Overall this is a solid approach to making Sandbox SDK classes workflow-serializable. The lazy client pattern via ensureClient() is clean, and the "use step" annotations are comprehensive. A few things worth addressing below.

[pranaygp]

Fragile: accessing parent private fields via (instance as any)

This duplicates the serialization logic from Command[WORKFLOW_SERIALIZE] and accesses sandboxId and cmd via as any casts because they are private on the parent class. If those field names are ever renamed, this will silently break.

Consider reusing the parent serializer:

static[WORKFLOW_SERIALIZE](instance: CommandFinished){return{
...Command[WORKFLOW_SERIALIZE](instance),exitCode: instance.exitCode,};}

This keeps CommandFinished serialization in sync with Command automatically.

[pranaygp]

Resolved — after rebasing onto #72, CommandFinished uses protected fields and accesses them directly in its serializer. No as any casts.

[pranaygp]

DisposableSandbox[WORKFLOW_DESERIALIZE] duplicates Sandbox[WORKFLOW_DESERIALIZE]

This is a near-copy of Sandbox[WORKFLOW_DESERIALIZE] — the only difference is the prototype used. Consider reusing the parent to avoid drift:

static[WORKFLOW_DESERIALIZE](data: {sandbox: ConvertedSandbox;
routes: SandboxRouteData[];
privateParams: Record<string,unknown>;}): DisposableSandbox{constinstance=Sandbox[WORKFLOW_DESERIALIZE](data);Object.setPrototypeOf(instance,DisposableSandbox.prototype);returninstanceasDisposableSandbox;}

[pranaygp]

Resolved — in #72's implementation, DisposableSandbox doesn't have its own WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE at all. No duplication.

[pranaygp]

Signal from concurrent callers is silently ignored

When stdout() and stderr() are called concurrently, only the signal from the first call is wired into getLogs(). The second caller's signal is ignored — it will wait for the first call to finish even if its own signal is aborted.

This was pre-existing behavior (the old code via this.logs() had the same issue), but worth noting now that this is explicitly step-compatible and more likely to be called in workflow contexts where cancellation semantics matter.

[pranaygp]

This is a pre-existing issue in the output caching logic from #72 — not introduced or changed by this PR (which only adds "use step" annotations). Leaving for a separate follow-up if needed.

[pranaygp]

nit: The error message says to use output(), stdout(), or stderr() instead — but these methods internally call getCachedOutput() which calls ensureClient() and then client.getLogs(). So the real distinction is that logs() requires a pre-existing client while the other methods can lazily reconstruct one. The error message is correct in its guidance but slightly misleading about why — it's not that logs() is inherently non-step-compatible, it's that it's synchronous and can't call the async ensureClient(). Maybe worth a small clarification:

"Cannot call logs() on a deserialized Command. " +
"logs() is synchronous and cannot lazily reconstruct the API client. " +
"Use output(), stdout(), or stderr() instead."

[pranaygp]

Resolved — in #72's implementation, logs() uses the lazy get client() getter which auto-creates the client from global credentials. There's no special error message for deserialized instances.

[pranaygp]

Minor: @workflow/serde is pinned to a beta pre-release (^4.1.0-beta.2). With the ^ range, this will accept any >=4.1.0-beta.2 <5.0.0 including future betas and the eventual stable release. Is that intentional? If the stable API is expected to be compatible, this is fine. If the beta API might still change, consider pinning more tightly (e.g., ~4.1.0-beta.2 or exact).

[pranaygp]

human: I think this is fine. we won't break serve in 4.x and we're going to 5.x soon on workflow

[pranaygp]

Resolved per above — staying with ^ range since serde won't break in 4.x.

[TooTallNate]

Superseded by #109, which re-implements this approach against the current tootallnate/serde branch with the additional fix of bundle: false in tsdown and the async ensureClient() pattern to keep APIClient out of the workflow bundle's module scope.

[TooTallNate]

Summary

Adds "use step" annotations to all API-calling async methods in the Sandbox SDK, building on the serialization support from #72. This allows Sandbox, Command, CommandFinished, and Snapshot instances to be used directly inside "use workflow" functions without needing manual step wrappers.

Changes

• Annotate all async API methods with "use step" in Sandbox, Command, CommandFinished, and Snapshot
• Simplify the workflow-code-runner example to call SDK methods directly in the workflow (removing the steps/sandbox.ts wrapper)

Before (manual step wrappers required)

// steps/sandbox.tsexportasyncfunctionexecute(sandbox: Sandbox,code: string){"use step";initCredentials();awaitsandbox.writeFiles([...]);constfinished=awaitsandbox.runCommand("node",["script.js"]);return{exitCode: finished.exitCode,stdout: awaitfinished.stdout(),stderr: awaitfinished.stderr()};}// workflows/code-runner.tsconstresult=awaitexecute(sandbox,code);

After (SDK methods are steps)

// workflows/code-runner.ts — no wrapper neededawaitsandbox.writeFiles([{path: "script.js",content: Buffer.from(code)}]);constfinished=awaitsandbox.runCommand("node",["script.js"]);conststdout=awaitfinished.stdout();

Test plan

• Verify workflow-code-runner example works end-to-end
• Confirm step replay correctly skips already-completed SDK calls

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
sandbox	Error		Mar 20, 2026 10:26pm
sandbox-cli	Ready	Preview, Comment	Mar 20, 2026 10:26pm
sandbox-sdk	Ready	Preview, Comment	Mar 20, 2026 10:26pm
sandbox-sdk-ai-example	Ready	Preview, Comment	Mar 20, 2026 10:26pm

[pranaygp]

Overall this is a solid approach to making Sandbox SDK classes workflow-serializable. The lazy client pattern via ensureClient() is clean, and the "use step" annotations are comprehensive. A few things worth addressing below.

[pranaygp]

Fragile: accessing parent private fields via (instance as any)

This duplicates the serialization logic from Command[WORKFLOW_SERIALIZE] and accesses sandboxId and cmd via as any casts because they are private on the parent class. If those field names are ever renamed, this will silently break.

Consider reusing the parent serializer:

static[WORKFLOW_SERIALIZE](instance: CommandFinished){return{
...Command[WORKFLOW_SERIALIZE](instance),exitCode: instance.exitCode,};}

This keeps CommandFinished serialization in sync with Command automatically.

[pranaygp]

Resolved — after rebasing onto #72, CommandFinished uses protected fields and accesses them directly in its serializer. No as any casts.

[pranaygp]

DisposableSandbox[WORKFLOW_DESERIALIZE] duplicates Sandbox[WORKFLOW_DESERIALIZE]

This is a near-copy of Sandbox[WORKFLOW_DESERIALIZE] — the only difference is the prototype used. Consider reusing the parent to avoid drift:

static[WORKFLOW_DESERIALIZE](data: {sandbox: ConvertedSandbox;
routes: SandboxRouteData[];
privateParams: Record<string,unknown>;}): DisposableSandbox{constinstance=Sandbox[WORKFLOW_DESERIALIZE](data);Object.setPrototypeOf(instance,DisposableSandbox.prototype);returninstanceasDisposableSandbox;}

[pranaygp]

Resolved — in #72's implementation, DisposableSandbox doesn't have its own WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE at all. No duplication.

[pranaygp]

Signal from concurrent callers is silently ignored

When stdout() and stderr() are called concurrently, only the signal from the first call is wired into getLogs(). The second caller's signal is ignored — it will wait for the first call to finish even if its own signal is aborted.

This was pre-existing behavior (the old code via this.logs() had the same issue), but worth noting now that this is explicitly step-compatible and more likely to be called in workflow contexts where cancellation semantics matter.

[pranaygp]

This is a pre-existing issue in the output caching logic from #72 — not introduced or changed by this PR (which only adds "use step" annotations). Leaving for a separate follow-up if needed.

[pranaygp]

nit: The error message says to use output(), stdout(), or stderr() instead — but these methods internally call getCachedOutput() which calls ensureClient() and then client.getLogs(). So the real distinction is that logs() requires a pre-existing client while the other methods can lazily reconstruct one. The error message is correct in its guidance but slightly misleading about why — it's not that logs() is inherently non-step-compatible, it's that it's synchronous and can't call the async ensureClient(). Maybe worth a small clarification:

"Cannot call logs() on a deserialized Command. " +
"logs() is synchronous and cannot lazily reconstruct the API client. " +
"Use output(), stdout(), or stderr() instead."

[pranaygp]

Resolved — in #72's implementation, logs() uses the lazy get client() getter which auto-creates the client from global credentials. There's no special error message for deserialized instances.

[pranaygp]

Minor: @workflow/serde is pinned to a beta pre-release (^4.1.0-beta.2). With the ^ range, this will accept any >=4.1.0-beta.2 <5.0.0 including future betas and the eventual stable release. Is that intentional? If the stable API is expected to be compatible, this is fine. If the beta API might still change, consider pinning more tightly (e.g., ~4.1.0-beta.2 or exact).

[pranaygp]

human: I think this is fine. we won't break serve in 4.x and we're going to 5.x soon on workflow

[pranaygp]

Resolved per above — staying with ^ range since serde won't break in 4.x.

[TooTallNate]

Superseded by #109, which re-implements this approach against the current tootallnate/serde branch with the additional fix of bundle: false in tsdown and the async ensureClient() pattern to keep APIClient out of the workflow bundle's module scope.

[TooTallNate]

Summary

Adds "use step" annotations to all API-calling async methods in the Sandbox SDK, building on the serialization support from #72. This allows Sandbox, Command, CommandFinished, and Snapshot instances to be used directly inside "use workflow" functions without needing manual step wrappers.

Changes

• Annotate all async API methods with "use step" in Sandbox, Command, CommandFinished, and Snapshot
• Simplify the workflow-code-runner example to call SDK methods directly in the workflow (removing the steps/sandbox.ts wrapper)

Before (manual step wrappers required)

// steps/sandbox.tsexportasyncfunctionexecute(sandbox: Sandbox,code: string){"use step";initCredentials();awaitsandbox.writeFiles([...]);constfinished=awaitsandbox.runCommand("node",["script.js"]);return{exitCode: finished.exitCode,stdout: awaitfinished.stdout(),stderr: awaitfinished.stderr()};}// workflows/code-runner.tsconstresult=awaitexecute(sandbox,code);

After (SDK methods are steps)

// workflows/code-runner.ts — no wrapper neededawaitsandbox.writeFiles([{path: "script.js",content: Buffer.from(code)}]);constfinished=awaitsandbox.runCommand("node",["script.js"]);conststdout=awaitfinished.stdout();

Test plan

• Verify workflow-code-runner example works end-to-end
• Confirm step replay correctly skips already-completed SDK calls

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
sandbox	Error		Mar 20, 2026 10:26pm
sandbox-cli	Ready	Preview, Comment	Mar 20, 2026 10:26pm
sandbox-sdk	Ready	Preview, Comment	Mar 20, 2026 10:26pm
sandbox-sdk-ai-example	Ready	Preview, Comment	Mar 20, 2026 10:26pm

[pranaygp]

Overall this is a solid approach to making Sandbox SDK classes workflow-serializable. The lazy client pattern via ensureClient() is clean, and the "use step" annotations are comprehensive. A few things worth addressing below.

[pranaygp]

Fragile: accessing parent private fields via (instance as any)

This duplicates the serialization logic from Command[WORKFLOW_SERIALIZE] and accesses sandboxId and cmd via as any casts because they are private on the parent class. If those field names are ever renamed, this will silently break.

Consider reusing the parent serializer:

static[WORKFLOW_SERIALIZE](instance: CommandFinished){return{
...Command[WORKFLOW_SERIALIZE](instance),exitCode: instance.exitCode,};}

This keeps CommandFinished serialization in sync with Command automatically.

[pranaygp]

Resolved — after rebasing onto #72, CommandFinished uses protected fields and accesses them directly in its serializer. No as any casts.

[pranaygp]

DisposableSandbox[WORKFLOW_DESERIALIZE] duplicates Sandbox[WORKFLOW_DESERIALIZE]

This is a near-copy of Sandbox[WORKFLOW_DESERIALIZE] — the only difference is the prototype used. Consider reusing the parent to avoid drift:

static[WORKFLOW_DESERIALIZE](data: {sandbox: ConvertedSandbox;
routes: SandboxRouteData[];
privateParams: Record<string,unknown>;}): DisposableSandbox{constinstance=Sandbox[WORKFLOW_DESERIALIZE](data);Object.setPrototypeOf(instance,DisposableSandbox.prototype);returninstanceasDisposableSandbox;}

[pranaygp]

Resolved — in #72's implementation, DisposableSandbox doesn't have its own WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE at all. No duplication.

[pranaygp]

Signal from concurrent callers is silently ignored

When stdout() and stderr() are called concurrently, only the signal from the first call is wired into getLogs(). The second caller's signal is ignored — it will wait for the first call to finish even if its own signal is aborted.

This was pre-existing behavior (the old code via this.logs() had the same issue), but worth noting now that this is explicitly step-compatible and more likely to be called in workflow contexts where cancellation semantics matter.

[pranaygp]

This is a pre-existing issue in the output caching logic from #72 — not introduced or changed by this PR (which only adds "use step" annotations). Leaving for a separate follow-up if needed.

[pranaygp]

nit: The error message says to use output(), stdout(), or stderr() instead — but these methods internally call getCachedOutput() which calls ensureClient() and then client.getLogs(). So the real distinction is that logs() requires a pre-existing client while the other methods can lazily reconstruct one. The error message is correct in its guidance but slightly misleading about why — it's not that logs() is inherently non-step-compatible, it's that it's synchronous and can't call the async ensureClient(). Maybe worth a small clarification:

"Cannot call logs() on a deserialized Command. " +
"logs() is synchronous and cannot lazily reconstruct the API client. " +
"Use output(), stdout(), or stderr() instead."

[pranaygp]

Resolved — in #72's implementation, logs() uses the lazy get client() getter which auto-creates the client from global credentials. There's no special error message for deserialized instances.

[pranaygp]

Minor: @workflow/serde is pinned to a beta pre-release (^4.1.0-beta.2). With the ^ range, this will accept any >=4.1.0-beta.2 <5.0.0 including future betas and the eventual stable release. Is that intentional? If the stable API is expected to be compatible, this is fine. If the beta API might still change, consider pinning more tightly (e.g., ~4.1.0-beta.2 or exact).

[pranaygp]

human: I think this is fine. we won't break serve in 4.x and we're going to 5.x soon on workflow

[pranaygp]

Resolved per above — staying with ^ range since serde won't break in 4.x.

[TooTallNate]

Superseded by #109, which re-implements this approach against the current tootallnate/serde branch with the additional fix of bundle: false in tsdown and the async ensureClient() pattern to keep APIClient out of the workflow bundle's module scope.

[TooTallNate]

Summary

Adds "use step" annotations to all API-calling async methods in the Sandbox SDK, building on the serialization support from #72. This allows Sandbox, Command, CommandFinished, and Snapshot instances to be used directly inside "use workflow" functions without needing manual step wrappers.

Changes

• Annotate all async API methods with "use step" in Sandbox, Command, CommandFinished, and Snapshot
• Simplify the workflow-code-runner example to call SDK methods directly in the workflow (removing the steps/sandbox.ts wrapper)

Before (manual step wrappers required)

// steps/sandbox.tsexportasyncfunctionexecute(sandbox: Sandbox,code: string){"use step";initCredentials();awaitsandbox.writeFiles([...]);constfinished=awaitsandbox.runCommand("node",["script.js"]);return{exitCode: finished.exitCode,stdout: awaitfinished.stdout(),stderr: awaitfinished.stderr()};}// workflows/code-runner.tsconstresult=awaitexecute(sandbox,code);

After (SDK methods are steps)

// workflows/code-runner.ts — no wrapper neededawaitsandbox.writeFiles([{path: "script.js",content: Buffer.from(code)}]);constfinished=awaitsandbox.runCommand("node",["script.js"]);conststdout=awaitfinished.stdout();

Test plan

• Verify workflow-code-runner example works end-to-end
• Confirm step replay correctly skips already-completed SDK calls

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
sandbox	Error		Mar 20, 2026 10:26pm
sandbox-cli	Ready	Preview, Comment	Mar 20, 2026 10:26pm
sandbox-sdk	Ready	Preview, Comment	Mar 20, 2026 10:26pm
sandbox-sdk-ai-example	Ready	Preview, Comment	Mar 20, 2026 10:26pm

[pranaygp]

Overall this is a solid approach to making Sandbox SDK classes workflow-serializable. The lazy client pattern via ensureClient() is clean, and the "use step" annotations are comprehensive. A few things worth addressing below.

[pranaygp]

Fragile: accessing parent private fields via (instance as any)

This duplicates the serialization logic from Command[WORKFLOW_SERIALIZE] and accesses sandboxId and cmd via as any casts because they are private on the parent class. If those field names are ever renamed, this will silently break.

Consider reusing the parent serializer:

static[WORKFLOW_SERIALIZE](instance: CommandFinished){return{
...Command[WORKFLOW_SERIALIZE](instance),exitCode: instance.exitCode,};}

This keeps CommandFinished serialization in sync with Command automatically.

[pranaygp]

Resolved — after rebasing onto #72, CommandFinished uses protected fields and accesses them directly in its serializer. No as any casts.

[pranaygp]

DisposableSandbox[WORKFLOW_DESERIALIZE] duplicates Sandbox[WORKFLOW_DESERIALIZE]

This is a near-copy of Sandbox[WORKFLOW_DESERIALIZE] — the only difference is the prototype used. Consider reusing the parent to avoid drift:

static[WORKFLOW_DESERIALIZE](data: {sandbox: ConvertedSandbox;
routes: SandboxRouteData[];
privateParams: Record<string,unknown>;}): DisposableSandbox{constinstance=Sandbox[WORKFLOW_DESERIALIZE](data);Object.setPrototypeOf(instance,DisposableSandbox.prototype);returninstanceasDisposableSandbox;}

[pranaygp]

Resolved — in #72's implementation, DisposableSandbox doesn't have its own WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE at all. No duplication.

[pranaygp]

Signal from concurrent callers is silently ignored

When stdout() and stderr() are called concurrently, only the signal from the first call is wired into getLogs(). The second caller's signal is ignored — it will wait for the first call to finish even if its own signal is aborted.

This was pre-existing behavior (the old code via this.logs() had the same issue), but worth noting now that this is explicitly step-compatible and more likely to be called in workflow contexts where cancellation semantics matter.

[pranaygp]

This is a pre-existing issue in the output caching logic from #72 — not introduced or changed by this PR (which only adds "use step" annotations). Leaving for a separate follow-up if needed.

[pranaygp]

nit: The error message says to use output(), stdout(), or stderr() instead — but these methods internally call getCachedOutput() which calls ensureClient() and then client.getLogs(). So the real distinction is that logs() requires a pre-existing client while the other methods can lazily reconstruct one. The error message is correct in its guidance but slightly misleading about why — it's not that logs() is inherently non-step-compatible, it's that it's synchronous and can't call the async ensureClient(). Maybe worth a small clarification:

"Cannot call logs() on a deserialized Command. " +
"logs() is synchronous and cannot lazily reconstruct the API client. " +
"Use output(), stdout(), or stderr() instead."

[pranaygp]

Resolved — in #72's implementation, logs() uses the lazy get client() getter which auto-creates the client from global credentials. There's no special error message for deserialized instances.

[pranaygp]

Minor: @workflow/serde is pinned to a beta pre-release (^4.1.0-beta.2). With the ^ range, this will accept any >=4.1.0-beta.2 <5.0.0 including future betas and the eventual stable release. Is that intentional? If the stable API is expected to be compatible, this is fine. If the beta API might still change, consider pinning more tightly (e.g., ~4.1.0-beta.2 or exact).

[pranaygp]

human: I think this is fine. we won't break serve in 4.x and we're going to 5.x soon on workflow

[pranaygp]

Resolved per above — staying with ^ range since serde won't break in 4.x.

[TooTallNate]

Superseded by #109, which re-implements this approach against the current tootallnate/serde branch with the additional fix of bundle: false in tsdown and the async ensureClient() pattern to keep APIClient out of the workflow bundle's module scope.

[TooTallNate]

Summary

Adds "use step" annotations to all API-calling async methods in the Sandbox SDK, building on the serialization support from #72. This allows Sandbox, Command, CommandFinished, and Snapshot instances to be used directly inside "use workflow" functions without needing manual step wrappers.

Changes

• Annotate all async API methods with "use step" in Sandbox, Command, CommandFinished, and Snapshot
• Simplify the workflow-code-runner example to call SDK methods directly in the workflow (removing the steps/sandbox.ts wrapper)

Before (manual step wrappers required)

// steps/sandbox.tsexportasyncfunctionexecute(sandbox: Sandbox,code: string){"use step";initCredentials();awaitsandbox.writeFiles([...]);constfinished=awaitsandbox.runCommand("node",["script.js"]);return{exitCode: finished.exitCode,stdout: awaitfinished.stdout(),stderr: awaitfinished.stderr()};}// workflows/code-runner.tsconstresult=awaitexecute(sandbox,code);

After (SDK methods are steps)

// workflows/code-runner.ts — no wrapper neededawaitsandbox.writeFiles([{path: "script.js",content: Buffer.from(code)}]);constfinished=awaitsandbox.runCommand("node",["script.js"]);conststdout=awaitfinished.stdout();

Test plan

• Verify workflow-code-runner example works end-to-end
• Confirm step replay correctly skips already-completed SDK calls

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
sandbox	Error		Mar 20, 2026 10:26pm
sandbox-cli	Ready	Preview, Comment	Mar 20, 2026 10:26pm
sandbox-sdk	Ready	Preview, Comment	Mar 20, 2026 10:26pm
sandbox-sdk-ai-example	Ready	Preview, Comment	Mar 20, 2026 10:26pm

[pranaygp]

Overall this is a solid approach to making Sandbox SDK classes workflow-serializable. The lazy client pattern via ensureClient() is clean, and the "use step" annotations are comprehensive. A few things worth addressing below.

[pranaygp]

Fragile: accessing parent private fields via (instance as any)

This duplicates the serialization logic from Command[WORKFLOW_SERIALIZE] and accesses sandboxId and cmd via as any casts because they are private on the parent class. If those field names are ever renamed, this will silently break.

Consider reusing the parent serializer:

static[WORKFLOW_SERIALIZE](instance: CommandFinished){return{
...Command[WORKFLOW_SERIALIZE](instance),exitCode: instance.exitCode,};}

This keeps CommandFinished serialization in sync with Command automatically.

[pranaygp]

Resolved — after rebasing onto #72, CommandFinished uses protected fields and accesses them directly in its serializer. No as any casts.

[pranaygp]

DisposableSandbox[WORKFLOW_DESERIALIZE] duplicates Sandbox[WORKFLOW_DESERIALIZE]

This is a near-copy of Sandbox[WORKFLOW_DESERIALIZE] — the only difference is the prototype used. Consider reusing the parent to avoid drift:

static[WORKFLOW_DESERIALIZE](data: {sandbox: ConvertedSandbox;
routes: SandboxRouteData[];
privateParams: Record<string,unknown>;}): DisposableSandbox{constinstance=Sandbox[WORKFLOW_DESERIALIZE](data);Object.setPrototypeOf(instance,DisposableSandbox.prototype);returninstanceasDisposableSandbox;}

[pranaygp]

Resolved — in #72's implementation, DisposableSandbox doesn't have its own WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE at all. No duplication.

[pranaygp]

Signal from concurrent callers is silently ignored

When stdout() and stderr() are called concurrently, only the signal from the first call is wired into getLogs(). The second caller's signal is ignored — it will wait for the first call to finish even if its own signal is aborted.

This was pre-existing behavior (the old code via this.logs() had the same issue), but worth noting now that this is explicitly step-compatible and more likely to be called in workflow contexts where cancellation semantics matter.

[pranaygp]

This is a pre-existing issue in the output caching logic from #72 — not introduced or changed by this PR (which only adds "use step" annotations). Leaving for a separate follow-up if needed.

[pranaygp]

nit: The error message says to use output(), stdout(), or stderr() instead — but these methods internally call getCachedOutput() which calls ensureClient() and then client.getLogs(). So the real distinction is that logs() requires a pre-existing client while the other methods can lazily reconstruct one. The error message is correct in its guidance but slightly misleading about why — it's not that logs() is inherently non-step-compatible, it's that it's synchronous and can't call the async ensureClient(). Maybe worth a small clarification:

"Cannot call logs() on a deserialized Command. " +
"logs() is synchronous and cannot lazily reconstruct the API client. " +
"Use output(), stdout(), or stderr() instead."

[pranaygp]

Resolved — in #72's implementation, logs() uses the lazy get client() getter which auto-creates the client from global credentials. There's no special error message for deserialized instances.

[pranaygp]

Minor: @workflow/serde is pinned to a beta pre-release (^4.1.0-beta.2). With the ^ range, this will accept any >=4.1.0-beta.2 <5.0.0 including future betas and the eventual stable release. Is that intentional? If the stable API is expected to be compatible, this is fine. If the beta API might still change, consider pinning more tightly (e.g., ~4.1.0-beta.2 or exact).

[pranaygp]

human: I think this is fine. we won't break serve in 4.x and we're going to 5.x soon on workflow

[pranaygp]

Resolved per above — staying with ^ range since serde won't break in 4.x.

[TooTallNate]

Superseded by #109, which re-implements this approach against the current tootallnate/serde branch with the additional fix of bundle: false in tsdown and the async ensureClient() pattern to keep APIClient out of the workflow bundle's module scope.

[TooTallNate]

Summary

Adds "use step" annotations to all API-calling async methods in the Sandbox SDK, building on the serialization support from #72. This allows Sandbox, Command, CommandFinished, and Snapshot instances to be used directly inside "use workflow" functions without needing manual step wrappers.

Changes

• Annotate all async API methods with "use step" in Sandbox, Command, CommandFinished, and Snapshot
• Simplify the workflow-code-runner example to call SDK methods directly in the workflow (removing the steps/sandbox.ts wrapper)

Before (manual step wrappers required)

// steps/sandbox.tsexportasyncfunctionexecute(sandbox: Sandbox,code: string){"use step";initCredentials();awaitsandbox.writeFiles([...]);constfinished=awaitsandbox.runCommand("node",["script.js"]);return{exitCode: finished.exitCode,stdout: awaitfinished.stdout(),stderr: awaitfinished.stderr()};}// workflows/code-runner.tsconstresult=awaitexecute(sandbox,code);

After (SDK methods are steps)

// workflows/code-runner.ts — no wrapper neededawaitsandbox.writeFiles([{path: "script.js",content: Buffer.from(code)}]);constfinished=awaitsandbox.runCommand("node",["script.js"]);conststdout=awaitfinished.stdout();

Test plan

• Verify workflow-code-runner example works end-to-end
• Confirm step replay correctly skips already-completed SDK calls

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
sandbox	Error		Mar 20, 2026 10:26pm
sandbox-cli	Ready	Preview, Comment	Mar 20, 2026 10:26pm
sandbox-sdk	Ready	Preview, Comment	Mar 20, 2026 10:26pm
sandbox-sdk-ai-example	Ready	Preview, Comment	Mar 20, 2026 10:26pm

[pranaygp]

Overall this is a solid approach to making Sandbox SDK classes workflow-serializable. The lazy client pattern via ensureClient() is clean, and the "use step" annotations are comprehensive. A few things worth addressing below.

[pranaygp]

Fragile: accessing parent private fields via (instance as any)

This duplicates the serialization logic from Command[WORKFLOW_SERIALIZE] and accesses sandboxId and cmd via as any casts because they are private on the parent class. If those field names are ever renamed, this will silently break.

Consider reusing the parent serializer:

static[WORKFLOW_SERIALIZE](instance: CommandFinished){return{
...Command[WORKFLOW_SERIALIZE](instance),exitCode: instance.exitCode,};}

This keeps CommandFinished serialization in sync with Command automatically.

[pranaygp]

Resolved — after rebasing onto #72, CommandFinished uses protected fields and accesses them directly in its serializer. No as any casts.

[pranaygp]

DisposableSandbox[WORKFLOW_DESERIALIZE] duplicates Sandbox[WORKFLOW_DESERIALIZE]

This is a near-copy of Sandbox[WORKFLOW_DESERIALIZE] — the only difference is the prototype used. Consider reusing the parent to avoid drift:

static[WORKFLOW_DESERIALIZE](data: {sandbox: ConvertedSandbox;
routes: SandboxRouteData[];
privateParams: Record<string,unknown>;}): DisposableSandbox{constinstance=Sandbox[WORKFLOW_DESERIALIZE](data);Object.setPrototypeOf(instance,DisposableSandbox.prototype);returninstanceasDisposableSandbox;}

[pranaygp]

Resolved — in #72's implementation, DisposableSandbox doesn't have its own WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE at all. No duplication.

[pranaygp]

Signal from concurrent callers is silently ignored

When stdout() and stderr() are called concurrently, only the signal from the first call is wired into getLogs(). The second caller's signal is ignored — it will wait for the first call to finish even if its own signal is aborted.

This was pre-existing behavior (the old code via this.logs() had the same issue), but worth noting now that this is explicitly step-compatible and more likely to be called in workflow contexts where cancellation semantics matter.

[pranaygp]

This is a pre-existing issue in the output caching logic from #72 — not introduced or changed by this PR (which only adds "use step" annotations). Leaving for a separate follow-up if needed.

[pranaygp]

nit: The error message says to use output(), stdout(), or stderr() instead — but these methods internally call getCachedOutput() which calls ensureClient() and then client.getLogs(). So the real distinction is that logs() requires a pre-existing client while the other methods can lazily reconstruct one. The error message is correct in its guidance but slightly misleading about why — it's not that logs() is inherently non-step-compatible, it's that it's synchronous and can't call the async ensureClient(). Maybe worth a small clarification:

"Cannot call logs() on a deserialized Command. " +
"logs() is synchronous and cannot lazily reconstruct the API client. " +
"Use output(), stdout(), or stderr() instead."

[pranaygp]

Resolved — in #72's implementation, logs() uses the lazy get client() getter which auto-creates the client from global credentials. There's no special error message for deserialized instances.

[pranaygp]

Minor: @workflow/serde is pinned to a beta pre-release (^4.1.0-beta.2). With the ^ range, this will accept any >=4.1.0-beta.2 <5.0.0 including future betas and the eventual stable release. Is that intentional? If the stable API is expected to be compatible, this is fine. If the beta API might still change, consider pinning more tightly (e.g., ~4.1.0-beta.2 or exact).

[pranaygp]

human: I think this is fine. we won't break serve in 4.x and we're going to 5.x soon on workflow

[pranaygp]

Resolved per above — staying with ^ range since serde won't break in 4.x.

[TooTallNate]

Superseded by #109, which re-implements this approach against the current tootallnate/serde branch with the additional fix of bundle: false in tsdown and the async ensureClient() pattern to keep APIClient out of the workflow bundle's module scope.

[TooTallNate]

Summary

Adds "use step" annotations to all API-calling async methods in the Sandbox SDK, building on the serialization support from #72. This allows Sandbox, Command, CommandFinished, and Snapshot instances to be used directly inside "use workflow" functions without needing manual step wrappers.

Changes

• Annotate all async API methods with "use step" in Sandbox, Command, CommandFinished, and Snapshot
• Simplify the workflow-code-runner example to call SDK methods directly in the workflow (removing the steps/sandbox.ts wrapper)

Before (manual step wrappers required)

// steps/sandbox.tsexportasyncfunctionexecute(sandbox: Sandbox,code: string){"use step";initCredentials();awaitsandbox.writeFiles([...]);constfinished=awaitsandbox.runCommand("node",["script.js"]);return{exitCode: finished.exitCode,stdout: awaitfinished.stdout(),stderr: awaitfinished.stderr()};}// workflows/code-runner.tsconstresult=awaitexecute(sandbox,code);

After (SDK methods are steps)

// workflows/code-runner.ts — no wrapper neededawaitsandbox.writeFiles([{path: "script.js",content: Buffer.from(code)}]);constfinished=awaitsandbox.runCommand("node",["script.js"]);conststdout=awaitfinished.stdout();

Test plan

• Verify workflow-code-runner example works end-to-end
• Confirm step replay correctly skips already-completed SDK calls

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
sandbox	Error		Mar 20, 2026 10:26pm
sandbox-cli	Ready	Preview, Comment	Mar 20, 2026 10:26pm
sandbox-sdk	Ready	Preview, Comment	Mar 20, 2026 10:26pm
sandbox-sdk-ai-example	Ready	Preview, Comment	Mar 20, 2026 10:26pm

[pranaygp]

Overall this is a solid approach to making Sandbox SDK classes workflow-serializable. The lazy client pattern via ensureClient() is clean, and the "use step" annotations are comprehensive. A few things worth addressing below.

[pranaygp]

Fragile: accessing parent private fields via (instance as any)

This duplicates the serialization logic from Command[WORKFLOW_SERIALIZE] and accesses sandboxId and cmd via as any casts because they are private on the parent class. If those field names are ever renamed, this will silently break.

Consider reusing the parent serializer:

static[WORKFLOW_SERIALIZE](instance: CommandFinished){return{
...Command[WORKFLOW_SERIALIZE](instance),exitCode: instance.exitCode,};}

This keeps CommandFinished serialization in sync with Command automatically.

[pranaygp]

Resolved — after rebasing onto #72, CommandFinished uses protected fields and accesses them directly in its serializer. No as any casts.

[pranaygp]

DisposableSandbox[WORKFLOW_DESERIALIZE] duplicates Sandbox[WORKFLOW_DESERIALIZE]

This is a near-copy of Sandbox[WORKFLOW_DESERIALIZE] — the only difference is the prototype used. Consider reusing the parent to avoid drift:

static[WORKFLOW_DESERIALIZE](data: {sandbox: ConvertedSandbox;
routes: SandboxRouteData[];
privateParams: Record<string,unknown>;}): DisposableSandbox{constinstance=Sandbox[WORKFLOW_DESERIALIZE](data);Object.setPrototypeOf(instance,DisposableSandbox.prototype);returninstanceasDisposableSandbox;}

[pranaygp]

Resolved — in #72's implementation, DisposableSandbox doesn't have its own WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE at all. No duplication.

[pranaygp]

Signal from concurrent callers is silently ignored

When stdout() and stderr() are called concurrently, only the signal from the first call is wired into getLogs(). The second caller's signal is ignored — it will wait for the first call to finish even if its own signal is aborted.

This was pre-existing behavior (the old code via this.logs() had the same issue), but worth noting now that this is explicitly step-compatible and more likely to be called in workflow contexts where cancellation semantics matter.

[pranaygp]

This is a pre-existing issue in the output caching logic from #72 — not introduced or changed by this PR (which only adds "use step" annotations). Leaving for a separate follow-up if needed.

[pranaygp]

nit: The error message says to use output(), stdout(), or stderr() instead — but these methods internally call getCachedOutput() which calls ensureClient() and then client.getLogs(). So the real distinction is that logs() requires a pre-existing client while the other methods can lazily reconstruct one. The error message is correct in its guidance but slightly misleading about why — it's not that logs() is inherently non-step-compatible, it's that it's synchronous and can't call the async ensureClient(). Maybe worth a small clarification:

"Cannot call logs() on a deserialized Command. " +
"logs() is synchronous and cannot lazily reconstruct the API client. " +
"Use output(), stdout(), or stderr() instead."

[pranaygp]

Resolved — in #72's implementation, logs() uses the lazy get client() getter which auto-creates the client from global credentials. There's no special error message for deserialized instances.

[pranaygp]

Minor: @workflow/serde is pinned to a beta pre-release (^4.1.0-beta.2). With the ^ range, this will accept any >=4.1.0-beta.2 <5.0.0 including future betas and the eventual stable release. Is that intentional? If the stable API is expected to be compatible, this is fine. If the beta API might still change, consider pinning more tightly (e.g., ~4.1.0-beta.2 or exact).

[pranaygp]

human: I think this is fine. we won't break serve in 4.x and we're going to 5.x soon on workflow

[pranaygp]

Resolved per above — staying with ^ range since serde won't break in 4.x.

[TooTallNate]

Superseded by #109, which re-implements this approach against the current tootallnate/serde branch with the additional fix of bundle: false in tsdown and the async ensureClient() pattern to keep APIClient out of the workflow bundle's module scope.