Read command results beyond HTTP success

HTTP success is only the transport result

The command route can return a normal JSON response while the process itself failed. Inspect status and exit_code before accepting stdout as a usable result. Lupin marks the run succeeded when the provider exit code is zero and failed otherwise, and also returns stdout, stderr, duration_ms and started_at. These fields describe the command execution response, not the correctness of a generated report or transformed file. An agent that merely sees a successful HTTP request can accidentally publish an error message as an artifact or continue with partially written output.

Use the streams for different questions

Stdout usually carries the program's intended output, while stderr often contains diagnostics, progress or warnings. A program may intentionally write useful warnings to stderr and still exit successfully, so nonempty stderr alone is not a universal failure rule. Conversely, a program can print friendly text and exit nonzero. Define the expected result contract for the actual tool you invoke. For a JSON-producing command, parse the output and check required fields after checking the process exit. For a file-producing command, verify that file's format and contents rather than relying on a printed success sentence.

Keep command output bounded and structured

Large logs make diagnosis harder and can overwhelm the agent's context. Redirect verbose tool output to a named file when appropriate and print a small summary with an explicit exit status. Avoid a pipeline that hides the failing command's exit behind a successful final utility. If the environment's shell supports pipefail, enable it intentionally; otherwise structure the script to preserve the relevant status. Do not assume a particular shell or package is installed without inspecting the environment. The public API does not define a universal output truncation policy for every provider, so bound noisy commands yourself.

{
  "command": "python -c 'import json; print(json.dumps({\"ok\": True}))'",
  "timeout_seconds": 30
}

Preserve the original response for review

Store a sanitized command identity, start time, exit code and the relevant output excerpt with the task. Keep secrets out of command strings and streams because command history and logs can retain operational information. The runs listing is useful for reconciliation but does not guarantee access to the original full stdout and stderr through Lupin's normalized history response. If the command response was lost, inspect history and artifacts instead of claiming the streams were reviewed. A provider error or request timeout can leave a command's effect uncertain even when no result JSON reached the caller.

Verify the artifact at the task level

Choose a semantic check that corresponds to the user's request: parse a generated JSON file, confirm required columns in a table or inspect the exported image. A zero exit code is necessary for many workflows but insufficient for an empty or incorrect artifact. Record which checks were actually run and which conclusions are source-reviewed only. After saving useful output, stop the sandbox and track cleanup independently. This result-reading discipline turns command execution into a reviewable workflow: the user can see what ran, what the process reported and why the artifact was accepted or rejected.

Sources & verification

Reviewed against the current Lupin route, provider adapter and shared input contracts, plus the linked official references. Examples were not run against live services.

• docs.python.org · 3 · library · subprocess.html ↗Checked 2026-11-05
• docs.boat.dev · long-running-tasks · command-history ↗Checked 2026-11-05

Prepared with AI assistance by Lupin editorial. How we research and maintain these guides.