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

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

---