Description
Executable Scripts store deterministic code as a Superpower with a declared language, code body, optional input/output contract, and runtime hints. The supported language vocabulary covers shell, Bash, PowerShell, JavaScript, Python, Ruby, and an “other” documentation case. Scripts complement model-driven Prompts and Skills when the required result depends on precise computation, filesystem work, a host command, or an exit status.
Runtime hints make execution needs explicit. A JSON object can declare environment-variable names, allowed network hosts, target operating systems, and interpreters. The run path parses the declaration, maps secrets and hosts into a deny-by-default capability grant, and applies a fixed execution timeout.
Selling Points
- Turns deterministic automation into a versioned, searchable workspace artifact rather than an opaque local file.
- Documents inputs, outputs, exit behavior, interpreter, and runtime dependencies alongside the code.
- Limits network and secret access to explicitly declared names and hosts.
- Blocks malformed capability declarations instead of silently widening sandbox access.
- Keeps scripts portable even when a workspace has not configured a live execution provider.
User Story
An analyst stores a Python Script that reads a supplied CSV and returns a validated JSON summary. Its runtime hints name one required API token and allow only api.example.com. When the analyst runs it in Dots, the request grants that resolved secret and host while leaving filesystem writes and unrelated network destinations denied.
Extension Surface
Script authors extend behavior by supplying code, selecting a supported language, documenting the I/O contract, and declaring runtime needs. packages/superpowers/src/internal/shapes/parse.ts accepts a whole JSON object or the first fenced JSON block, while packages/code-execution/src/grants.ts is the single grant builder that converts declared environment and host needs into bounded sandbox capabilities.
Capabilities & Limits
Scripts can store seven language choices, preserve source history, validate strict runtime-hint shapes, derive scoped secret and network grants, and execute through the configured code-execution provider. Prose-only hints declare no capabilities, and invalid JSON or smuggled fields produce an explicit parse failure.
The other language documents an unlisted interpreter but cannot run in Dots. A workspace without a configured executor cannot execute the body. Operating-system and interpreter hints are informational in this package; only environment names and hosts narrow the capability grant. The run path uses a fixed 60-second limit, and specialized Hook or Plugin packaging belongs to other features.
Implementation Map
packages/superpowers/src/internal/templates/script.template.tspackages/superpowers/src/internal/shapes/parse.tspackages/code-execution/src/grants.tsapps/web/src/modules/dotabases/script-editor/exec-request.tsapps/web/src/modules/dotabases/script-editor/ScriptEditor.tsx