Safety & billing

Safe by design.

The tool surface separates reading from doing. Consequential tools are clearly marked and never run silently.

Reads vs. consequential tools

Read tools — health, list, get, source, live values, history, search-context, and the status polls — change nothing and cost nothing. Consequential tools are billable model runs or state changes: plcs_interpret, plcs_generate_code, plcs_start_analysis, plcs_save_version, plcs_ingest_project. Their tool descriptions are annotated so a well-behaved client asks you to confirm before running them.

Generate proposes, never deploys

plcs_generate_code returns a reviewable proposal and creates no version — it changes nothing in the project. Persisting requires a separate plcs_save_version (needs code_write). The flow is generate → human review → save.

For enterprise per-project organizations, ingesting a new billable project returns 402 billing_acknowledgement_required with a projected cost. The assistant must disclose that cost and only retry with acknowledge_billing: true on your explicit go-ahead — it must never acknowledge on its own. A 402 billing_setup_required means billing isn't set up yet — do that in the desktop app first, then retry.

json
{
  "error": "billing_acknowledgement_required",
  "userMessage": "This organization is billed per project. Uploading this project adds a new billable project (about $500.00 USD).",
  "billing": {
    "price_per_project_cents": 50000,
    "currency": "usd",
    "billed_count_after": 3
  }
}

Spend cap

Billable tools fail with a spend-limit error when the organization is paused at its API spend limit. The assistant should surface it (you can raise the limit in Settings) and not retry automatically.

Idempotent writes

Writes accept an optional idempotency_key — omit it and the server mints one per call. Retrying with the same key replays the original result instead of running again, so a dropped connection never double-bills.