Run a Luau snippet with a watchdog timeout
run-with-timeoutExecute a Luau snippet under a watchdog timeout so code that hangs on a yield returns timedOut instead of blocking the call forever.
Instructions
Run a Luau snippet under a WATCHDOG: it executes on its own thread and this tool polls a done flag against an os.clock() deadline, so a snippet that hangs on a YIELD (a yield that never resumes, a :Wait() on a signal that never fires) cannot block the round trip forever — after timeoutSec you get a clean { timedOut = true } instead of waiting out the whole connector timeout. Use this any time you are about to run code that MIGHT hang or take an unknown amount of time. The snippet is COMPILED FIRST via loadstring (a syntax error returns { error } and nothing runs), then started with task.spawn; the watchdog waits with task.wait until either the thread sets its done flag or the deadline passes. LIMITATION: Luau is cooperatively scheduled, so the watchdog can only fire when the snippet YIELDS. A snippet that never yields (e.g. while true do end or a tight CPU loop with no task.wait) runs synchronously inside task.spawn, so the watchdog loop never gets to run and the round trip still blocks until the connector timeout. Put a task.wait() inside long loops if you want the watchdog to be able to interrupt them. IMPORTANT: a timeout REPORTS that the snippet did not finish in time, but it does NOT kill the runaway thread — the executor keeps running it in the background (and it may keep consuming CPU). Prefer snippets that can finish, and keep timeoutSec sane. If the snippet completes in time, its FIRST return value is encoded via __encVal and returned; a runtime error inside it is captured in error. Requires loadstring, the task library, and os.clock (all guarded). Returns { completed, timedOut, elapsedMs, result?, error? } or { error }. Signature: { code: string, timeoutSec: any?, threadContext: number? }. Phase: act; cost=medium; idempotency=contextual-write. Requires: active-client, explicit-mutation-approval, validated-source. Produces: operation-receipt. Verify with: assert-state. Safety: MUTATING; executes caller-selected behavior in the live client. On failure: inspect tool-schema for exact fields, defaults, constraints, and an invocation example.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | The Luau snippet to run under the watchdog. Compiled with loadstring and run on its own thread. To report a value back, `return` it (only the first return value is captured, encoded as a serializable scalar/string). | |
| timeoutSec | No | How long to let the snippet run before giving up and reporting timedOut, in seconds (default 5, clamped 0.1..60). On timeout the snippet is NOT killed — it keeps running in the background; this only stops THIS tool from waiting. | |
| threadContext | No | Optional Roblox thread identity for this call; omit it to use the server default. |