Skip to contents

Watch an NLME job until it finishes or the server's watch budget elapses

wait_for_nlme_job.Rd

The preferred way for an agent to wait on a long fit/bootstrap/SCM job: it blocks server-side, polling the job status internally, and returns once the job reaches a terminal state (succeeded/failed/dead/not_found) or the watch budget elapses. This turns many agent poll turns into a single blocking tool call. If the job is still running when the call returns (watch$terminal is FALSE), simply call again to resume watching.

Usage

wait_for_nlme_job(
  job_id,
  project_dir = ".",
  max_wait_seconds = NULL,
  detail = c("compact", "full")
)

Arguments

job_id

Job id from start_nlme_job().

project_dir

Project root.

max_wait_seconds

Optional direct-R override for the per-call watch budget (seconds), clamped to 0..600 AND to the launch-configured cap. When NULL (the default) the launch-configured budget is used; 0 makes the call a single-shot status check. Values above the cap are silently clamped to the cap.

Value

The same list as get_nlme_job_status(), plus a watch block with max_wait_seconds, poll_seconds, source ("argument"/"launch_config"/"default"), and terminal (TRUE when the job reached a terminal state), and the agent-facing next_action directive (tool/args/reason; the single next call to make - NULL when none applies) with requires_user_attention when a job is stalled or terminal-without-success. While running in the default compact detail, only job_id, state, pid_alive, watch, progress, next_action, and (when set) requires_user_attention are returned.

Details

The watch budget comes from the server's launch configuration (launch_certara_mcp()'s job_watch_wait_seconds, set per client by write_mcp_config() in the Certara.R host) and is treated as a HARD UPPER BOUND: the internal poll interval is fixed at 5 seconds and the MCP schema does not expose max_wait_seconds to the agent. The direct-R max_wait_seconds argument is retained for compatibility - it may SHORTEN the budget (down to 0 for a single-shot check) but any value at or above the launch cap is silently clamped to the cap.

st <- wait_for_nlme_job(job_id, project_dir)
while (!st$watch$terminal) {            # still running after the budget
  st <- wait_for_nlme_job(job_id, project_dir)
}
artifact_dir <- st$artifact_dir

See also

get_nlme_job_status() for a single-shot snapshot, collect_nlme_job() to gather results once terminal.