# RequestPackage

Request a Python wheel that is not already available, so an approver can install
it into **this workspace** and let the run continue.

## When to use it

You tried to `import somelib` (in `Bash` running `python3`, or `RunUserScript`)
and it failed with `ModuleNotFoundError`, and the library is **not** in the
preinstalled set. Instead of retrying `pip install` (which is blocked in the
sandbox), call:

```
RequestPackage({ name: "httpx", reason: "need an async HTTP client for the API calls" })
RequestPackage({ name: "pandas==2.2.2", reason: "pinned for reproducibility" })
```

- `name` — the package. Either a bare name (`httpx`) or an exact pin
  (`httpx==0.27.0`). **Only `name==version` pins are accepted** — ranges
  (`>=`, `~=`) and URLs/extras are rejected (the overlay must be reproducible).
- `reason` — a concrete justification. It is shown to the approver.

## What happens

- **Interactive runs (a user is watching the chat):** the movement pauses and an
  Approve / Deny card appears in the chat. When a task-write user (owner / admin /
  space editor) approves, the wheel is installed into this workspace's private
  overlay and the run resumes automatically — now `import` works. If denied, you
  continue without it.
- **Non-interactive runs (subtasks / scheduled):** the request is recorded (the
  user finds it later) and you proceed **without** the package. Don't block on it —
  finish with what you have, or `complete({status:"needs_user_input"})` if you
  genuinely can't proceed.

## Rules and limits

- Wheels only, from a fixed package index. No source builds, no arbitrary index.
- A package that would shadow the standard library or a preinstalled package
  (e.g. `os`, `numpy`, `pandas`) is rejected — those are already importable.
- If the package is already installed in this workspace, the tool tells you to
  just `import` it (no approval needed).
- The install is per-workspace. Other workspaces do not see it.
- You cannot approve your own request — approval is a human/operator action.

## After approval

The run re-enters the same step. Re-run your Python; the import now succeeds. If
you call `RequestPackage` again for the same package, it reports "already
installed".

Related: preinstalled packages are listed in the error you get from a blocked
`pip install`. Workspace-wide package management (for operators) lives in
**Settings → the workspace's Python packages panel**.