swallow/maestro
1
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases 1 Wiki Activity
maestro/docs/tools/requestpackage.md
oss-sync 77ee3bc426
Some checks are pending
CI / build-and-test (push) Waiting to run
Details
sync: update from private repo (ddadfd71)
2026-07-08 23:35:00 +00:00

2.4 KiB
Raw Blame History

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.