Add step.sandbox.python()

[jpwilliams]

Summary

Adds step.sandbox.python(), a managed-lifecycle Sandbox that runs Python code and can take input.

Direct step usage

Use Python from TS, with the sandbox's lifecycle managed for you.

inputs become variables accessible by the code.

const stats = await step.sandbox.python("stats", `
  import statistics
   
  return {"mean": statistics.mean(values)}
`, {
  input: { values: [1, 2, 3, 4] },
});

Reusable functions

Create a reusable function usable during any run.

Output can also be typed and validated using any StandardSchema-compliant schema library.

import { step } from "inngest";
import { z } from "zod";

export const stats = async (id: string, values: number[]) => {
  return step.sandbox.python(id, `
    import statistics

    return {"mean": statistics.mean(values), "stdev": statistics.stdev(values)}
  `, {
    input: { values },
    schema: { output: z.object({ mean: z.number(), stdev: z.number() }),
  });
};

// later in a run
const { mean } = await stats("get-stats", [1, 2, 3, 4]);

Trace

Checklist

• Added a docs PR that references this PR N/A Later bump
• Added unit/integration tests
• Added changesets if applicable

Related

• Based on Add plumbing for TS/PY snippets in Sandboxes #1778

[changeset-bot]

🦋 Changeset detected

Latest commit: e815586

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
inngest	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[greptile-apps]

Confidence Score: 3/5

[Medium impact] Adds Python code execution in sandboxes.

Fix silent loss of large Python results and the missing advertised schema support before merging.

Findings

1.  Large Python results disappear ▶
2.  Schema example does not work ▶
3.  Invalid calls keep sandboxes alive ▶

Fix with agent prompt

### Issue 1
packages/inngest/src/components/sandbox/runners.ts:87-91
`runCode` ignores `output` from `commands.run` and parses potentially shortened `stdout`. For example, `return 'x' * 3000000` exceeds the 2 MiB limit. The saved output keeps only the tail, removing `__INNGEST_RESULT__`, so `parseRunnerOutput` returns `undefined`. The one-shot runner then destroys the sandbox and reports success with the wrong result.

Detect a missing result caused by truncation and fail clearly instead of treating it as no return value.

### Issue 2
packages/inngest/src/components/sandbox/runners.ts:24-29
`RunnerOptions` has no `schema` option, and `runCode` returns parsed JSON without checking an output schema. The PR's advertised `schema: { output: z.object(...) }` example therefore fails TypeScript's option check and cannot infer or validate its result.

Add the promised schema support and a test covering inference and invalid output.

### Issue 3
packages/inngest/src/components/sandbox/runners.ts:136-141
`createOneShotRunner` creates the sandbox before `buildRunner` checks the input and payload size. Invalid input or a payload over 16 KiB throws `SandboxValidationError`, which is retryable and does not trigger cleanup while attempts remain. The same invalid payload then fails on every retry while keeping the sandbox alive.

Build and validate the command before creating the sandbox to avoid unnecessary allocation and retries.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Adds step.sandbox.python() with managed sandbox creation and cleanup, plus python() on existing durable sandbox handles.

• Sandbox callers can run Python and get its returned value.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A["step.sandbox.python()"] --> B["Create sandbox"]
  B --> C["Build and validate command"]
  C --> D["Run durable command"]
  D --> E["Save output, keeping only its tail if too large"]
  E --> F["Check exit code and parse result"]
  F --> G["Destroy sandbox on success or final failure"]
  G --> H["Return result or throw"]

Loading

_{Reviews (1) · Last reviewed commit: "chore: drop changesets already released ..." · Reviewed by Greptile}

[jakobevangelista]

should we account for serialization in the return type here? with schema.output: z.coerce.date(), TS says we get a Date, but after replay it’s a string

i repro’d value.getUTCFullYear() compiling and then throwing at runtime with both step.sandbox.python() and step.sandbox.typescript(). should we apply the same output typing as step.run?

[jpwilliams]

Ah nice, aye we'll Jsonify here atm