run — scrollport

run is the only control tool that spends money or calls a provider. It can start a new catalog-tool execution or resume one already started.

Signatures

Start a run:

code

run({ tool_id, input, confirm?, wait_seconds? })

Resume a run:

code

run({ run_id, wait_seconds? })

Example start request:

code

{
  "name": "run",
  "arguments": {
    "tool_id": "<tool_id from discover>",
    "input": { "<field from inspect>": "<your value>" },
    "wait_seconds": 0
  }
}

Input fields

Field	Type	Meaning
`tool_id`	string	The selected catalog tool. Required for a new run.
`input`	object	The inspected tool's input. Required for a new run.
`confirm`	boolean	Only `true` after a human approves a quoted estimate.
`wait_seconds`	integer, 0–120	How long to wait; defaults to 50 seconds.
`run_id`	string	Resume an existing run instead of starting one.

Return and money behavior

A completed result includes run_id, status, optional result and artifacts, cost_estimated, cost_final and a display cost. A still-running call returns a run_id; resuming it starts nothing and costs nothing.

The server validates before placing a hold. A confirmation-threshold response is confirmation_required; show its estimate to the human and retry the identical input with confirm: true only after they agree. A failed run releases its entire hold and is not billed.

Common errors

Missing tool_id and run_id: choose one valid mode.
run_id mixed with tool_id or input: remove the new-run fields.
connection_required: give the human connect_url, then inspect again.
insufficient_balance: give the human topup_url; an agent cannot add funds.
Invalid input: read the returned hint and corrected example.

Read wallet before a batch and runs and recovery when a call is asynchronous.