Flow Control Interfaces

Introduction

Flow Control Interfaces:
Provides task script sub-script invocation, background concurrent execution, and task pause/resume/stop logic control.

Important: The following functions are automatically injected into the task script execution environment by the task engine at runtime. They can be called directly without import and are only available in task scripts executed via /sdk/execute_task.

Purpose	Python
Execute Sub-script Synchronously	✔
Execute Sub-script in Background	✔
Pause Task	✔
Resume Task	✔
Stop Task	✔

Sub-script Invocation

Python Interface

run_script(source, parameters=None)

Function Description
Execute a sub-script synchronously, blocking until the sub-script completes. The sub-script runs in a shallow copy of the parent script's namespace, with access to all preloaded APIs, but variable writes in the sub-script do not affect the parent namespace.

Parameter Description

Parameter Name	Type	Required/Default	Description
source	str	Required	task_id or path relative to $DAYSTAR_DATA_ROOT/scripts/ (no .py suffix needed).
parameters	dict	None	Parameter dictionary injected into the sub-script namespace; the sub-script accesses values via parameters["key"].

Return Value

No return value. Raises ScriptError on exception (with original_exc attribute containing the original exception), or FileNotFoundError if script not found.

Example

# Execute sub-script sequentially
run_script("patrol_task")

# Pass parameters to sub-script
run_script("patrol_task", parameters={"zone": "A", "speed": 0.5})

---

run_parallel_script(source, parameters=None)

Function Description
Execute a sub-script asynchronously in a background daemon thread. Returns a ThreadHandle immediately without blocking the main script. The background thread is controlled by a cooperative tracer: when the main task is paused, the background thread pauses synchronously; thread exceptions are only logged to stderr and do not affect main script execution.

Parameter Description

Parameter Name	Type	Required/Default	Description
source	str	Required	task_id or path relative to $DAYSTAR_DATA_ROOT/scripts/ (no .py suffix needed).
parameters	dict	None	Parameter dictionary injected into the sub-script namespace.

Return Value

Type	Description
ThreadHandle	Background thread handle. join(timeout) waits for completion; is_done() checks if finished; cancel() sends a cancel signal.

Example

# Start background monitor, main script continues
handle = run_parallel_script("monitor_battery")

navigation_to_location("PointA")
navigation_to_location("PointB")

handle.join()  # Optional: wait for monitor thread to finish

Lifecycle Control

Python Interface

pause_application()

Function Description
Pause task execution at the current code position and wait for an external /sdk/resume_task signal to continue. Recommended to call between operations, not during active navigation.

Parameter Description

No parameters.

Return Value

No return value.

Example

navigation_to_location("room_A")
pause_application()   # Wait for manual confirmation here
navigation_to_location("room_B")

---

resume_application()

Function Description
Write a resume signal to trigger a currently paused task to continue execution. Typical usage: wake up the main script from a background thread to implement a "wait for condition to be met" pattern.

Parameter Description

No parameters.

Return Value

No return value.

Example

# watchdog.py (background sub-script)
# Wake up main script when condition is met
if condition_met:
    resume_application()

# Main script
handle = run_parallel_script("watchdog")
pause_application()   # Wait for watchdog to wake up
navigation_to_location("next_point")

---

stop_application()

Function Description
Immediately terminate the current task (including all background threads) with a clean exit. Execution flow: sends cancel signal to all background threads → raises SystemExit(0) → engine marks task as STOPPED state.

Parameter Description

No parameters.

Return Value

No return value (does not return; terminates directly).

Example

battery = get_battery_state()
if battery.is_valid and battery.battery_state.percentage < 10:
    stop_application()  # Insufficient battery, safe exit

navigation_to_location("PointA")