Task Manager

Manage persisted task definitions stored on the agent.

nimbus task <command>

Command	Description
list	List configured tasks
get <task-id-or-name>	Show a single task definition as JSON
add <path>	Add a task from a JSON file; the agent generates the task_id
update <path> [--task-ref <task-id-or-name>]	Replace an existing task from a JSON file
delete <task-id-or-name>	Delete a task by id or unique name
list-running	List currently running task executions
monitor	Monitor task run lifecycle updates
history [task-id-or-name] [--limit <n>]	List persisted task run history
history-get <run-id>	Show one persisted task run history record
export <path>	Export the full task catalog to a JSON file
import <path> [--replace-existing]	Import tasks from a JSON file and optionally replace the existing catalog
run <task-id-or-name>	Start a task immediately
cancel <task-id-or-name>	Cancel a currently running task

Current runtime scope:

• Manual execution and persisted triggers are supported
• Delay, embedded allowlisted RunScript, local RunScript, PublishRosJson, Nav2Goal, RebootRobotComputer, and AgentSystemReload subtasks are supported
• Set maxIterations to a value greater than 0 to repeat the full subtask list that many total times
• Task names are required and must be unique after trimming and case normalization
• timeout: 0s or an omitted timeout means no timeout
• PublishRosJson is supported in two modes:
  • publish-only when responseStreamSource is omitted
  • publish-and-wait when responseStreamSource and responseSuccessValue are provided
• The task contract carries ROS topic name/type only; ROS2 domain comes from agent settings
• Response wait currently uses first-message-wins semantics on the configured response topic
• Sample allowlisted scripts are available under sample/emit_five_beeps, sample/write_marker, and sample/fail_with_message
• Local task scripts can be placed under <config-folder>/scripts and referenced by file name with scriptDomain set to scripts or local, or omitted

For Nav2Goal, the Agent ends the subtask on the third rejected submission or the tenth ABORTED result. Rejection and abort counts are separate, and each retry waits one second. SUCCEEDED and Nav2 CANCELED end the subtask immediately. A configured timeout covers setup, all attempts, status waits, and retry delays. These outcomes advance to the next subtask, including a following script; task completion therefore does not guarantee successful arrival or recording. maxIterations repeats the entire sequence and does not configure navigation retries.

cancel stops the whole task. Timeout or cancellation of the current step requests Nav2 goal cancellation before advancing, with up to five seconds for cleanup. A cancellation acknowledgment does not confirm that Nav2 reached CANCELED or that the robot physically stopped.

history-get shows execution IDs/iterations, navigation attempts and observed goal IDs/statuses, script process IDs/exit codes, cancellation replies, and timestamped stdout/stderr. Retention keeps up to 16 KiB combined output per script execution, 64 KiB output and 1,024 events per run, and 20 MiB retained detail overall. Dropped counts and expired-detail markers make missing evidence explicit. A nonzero script exit code is recorded and execution continues. Older histories can lack these details. The Agent-local history UI shows the same evidence, and debug bundles include a bounded tasks domain.

Examples

# List tasks
nimbus task list

# Start a task immediately by unique name
nimbus task run "beep-loop-smoke-test"

# Update a task by unique name
nimbus task update ./task.json --task-ref "beep-loop-smoke-test"

# List currently running executions
nimbus task list-running

# Monitor task lifecycle updates
nimbus task monitor

# List recent runs for one task
nimbus task history "beep-loop-smoke-test" --limit 20

# Show a full persisted run record
nimbus task history-get "<run-id>"

# Cancel a running task by id or unique name
nimbus task cancel "beep-loop-smoke-test"

# Export the current task catalog
nimbus task export ./tasks.json

# Import and replace the existing task catalog from a file
nimbus task import ./tasks.json --replace-existing

Task JSON examples

Publish only:

{
  "name": "publish-only-example",
  "enabled": true,
  "subtasks": [
    {
      "ordinal": 1,
      "name": "send-command",
      "publishRosJson": {
        "requestStreamSource": {
          "ros2Topic": {
            "name": "/robot/command",
            "type": "std_msgs/msg/String"
          }
        },
        "requestJson": "{\"data\":\"start\"}"
      }
    }
  ]
}

Publish and wait for allowed:

{
  "name": "permission-example",
  "enabled": true,
  "maxIterations": 3,
  "subtasks": [
    {
      "ordinal": 1,
      "name": "request-permission",
      "timeout": "10s",
      "publishRosJson": {
        "requestStreamSource": {
          "ros2Topic": {
            "name": "/task/permission/request",
            "type": "std_msgs/msg/String"
          }
        },
        "requestJson": "{\"data\":\"ask for permission\"}",
        "responseStreamSource": {
          "ros2Topic": {
            "name": "/task/permission/response",
            "type": "std_msgs/msg/String"
          }
        },
        "responseSuccessValue": "allowed"
      }
    }
  ]
}

Current limitation:

• response wait is not correlated; the first message received on the response topic is the one evaluated

---