Add per-run cost reports and hosted upload for summarize-pdf

[lchoquel]

Summary

• Cost reports on every run — a new shared piper/usage.py reads per-call usage off the SDK result (usage_from_results for the durable modes' typed RunResults.tokens_usages, usage_from_execute for blocking) and prints a per-call cost report (pipe, model, tokens in→out, USD, total) to stderr, after the JSON result on stdout. Unpriced calls (cost is None — mock / own-GPU / dry-run) are excluded from the total; token categories are never summed. Detached prints from wait/result (collection time), not the start-only demos.
• Hosted file upload for summarize-pdf (breaking) — the document is uploaded up front with client.upload_file (new inputs.upload_document_input) and the run request carries only the returned pipelex-storage:// URI, replacing the previous inline base64 data: URL. build_document_input(path, uri) becomes the pure envelope builder; piper/errors.py gains hints for the file-upload error family.
• Lifecycle helpers return (main_stuff, RunUsage) (breaking) — execute_pipe, start_and_wait, and detached's attend_run now return the resolved main output and the run's usage so the commands can print the cost report.
• Docs cleanup — dropped the stale-prone "shared modules" count per the workspace no-hardcoded-counts rule (kept the structural "three execution modes" constant intact).

Verify

• make agent-check — lint + type checks
• make agent-test — offline suite (inference/API markers excluded)

🤖 Generated with Claude Code

https://claude.ai/code/session_016xWB4B8DjEYbiffrjg3dsS

[greptile-apps]

Greptile Summary

This PR adds usage reporting and hosted PDF uploads to the CLI. The main changes are:

• Per-call token and cost reports on stderr.
• Hosted uploads for summarize-pdf inputs.
• Usage-aware lifecycle return values across all execution modes.
• Upload error hints, SDK updates, and documentation.

Confidence Score: 5/5

This looks safe to merge.

No blocking issues found in the changed code.

T-Rex Logs

What T-Rex did

• Inspected the full agent test output to understand the test run results.
• Performed blocker verification by comparing git status and git ls-files to assess the bootstrap script's presence in the checkout.
• Noted procedural guidance from the task, specifically that dependencies were not reinstalled, hosted tests were not attempted, and make agent-check was not run.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
piper/usage.py	Adds normalized usage extraction and cost-report rendering.
piper/inputs.py	Replaces inline PDF encoding with hosted upload and URI envelope construction.
piper/blocking/cli.py	Adds usage reporting and hosted PDF upload to blocking execution.
piper/attended/cli.py	Adds usage reporting and hosted PDF upload to attended execution.
piper/detached/cli.py	Reports usage when detached results are collected and uploads PDFs before starting runs.
piper/errors.py	Adds actionable messages for hosted upload failures.

Sequence Diagram

sequenceDiagram
participant CLI
participant Upload as Upload API
participant Run as Run API
CLI->>Upload: Upload local PDF
Upload-->>CLI: Storage URI
CLI->>Run: Start run with Document URI
Run-->>CLI: Main output and usage
CLI-->>CLI: Print JSON to stdout
CLI-->>CLI: Print cost report to stderr

Loading

_{Reviews (1): Last reviewed commit: "Add per-run cost reports and hosted uplo..." | Re-trigger Greptile}