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, the analysis read, and the export polls — change nothing and cost nothing. Consequential tools are billable model runs or state changes: plcs_ask_project, plcs_propose_code, plcs_save_version, plcs_request_live_tags. Their tool descriptions are annotated so a well-behaved client asks you to confirm before running them.

Generate proposes, never deploys

plcs_propose_code returns a reviewable proposal and creates no version — it changes nothing in the project. It is also a two-step call: a prompt returns a plan, and only approving that plan returns code, so the change is reviewed before it is written. Persisting is a separate plcs_save_version (needs code_write). The flow is propose → approve the plan → human review → save.

Per-project billing

Organizations billed per project confirm that charge when a machine is onboarded, which happens in the app or through a version-source connector. There is no ingest tool, so an assistant can never add a billable project and never has a cost to acknowledge. plcs_save_version adds a version, not a project, on any plan.

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.