mobile-debug-mcp 0.34.0 → 0.36.0

package/src/debugger/ios-worker.ts

@@ -0,0 +1,49 @@
+import { fileURLToPath } from 'node:url'
+import { getXcrunCmd } from '../utils/ios/utils.js'
+import { iosExec } from './ios.js'
+import { DebuggerProcess, type WorkerEvent, type DebugWorker } from './worker.js'
+import { DebuggerError } from './diagnostics.js'
+export const iosCapabilities = { attach: true, breakpoints: true, stacks: true, locals: true, step: true, resume: true,
+  evaluation: false, mutation: false, coroutines: false, native: false, async_execution_inspection: true, async_stepping: true }
+export const iosLimitations = ['IOS_SIMULATOR_ONLY', 'DEBUG_METADATA_REQUIRED', 'SHALLOW_LOCALS', 'ALL_THREADS_SUSPEND', 'DEVICE_WIDE_UI_GUARD', 'ASYNC_STEPPING_TOOLCHAIN_DEPENDENT', 'AGGREGATE_VALUES_TYPE_ONLY', 'NO_TASK_ENUMERATION']
+export const iosWorkerSource = fileURLToPath(new URL('../../src/debugger/lldb/worker.py', import.meta.url))
+let prepared: Promise<{ python: string; env: NodeJS.ProcessEnv }> | undefined
+export function prepareIOSWorker() {
+  prepared ??= (async () => {
+    if (process.platform !== 'darwin') throw new DebuggerError('DEBUGGER_UNSUPPORTED')
+    const pythonPath = await iosExec(getXcrunCmd(), ['lldb', '-P'])
+    const python = await iosExec(getXcrunCmd(), ['--find', 'python3'])
+    // Ignore user Python startup/customisation and LLDB init files.
+    const env = { PATH: process.env.PATH, HOME: process.env.HOME, PYTHONPATH: pythonPath, PYTHONNOUSERSITE: '1' }
+    const ready = await iosExec(python, ['-s', '-B', '-c', 'import lldb; d=lldb.SBDebugger.Create(False); print("ready" if d.IsValid() else "unavailable"); lldb.SBDebugger.Destroy(d)'], env)
+    if (ready !== 'ready') throw new DebuggerError('DEBUGGER_UNSUPPORTED')
+    return { python, env }
+  })().catch(error => { prepared = undefined; throw error })
+  return prepared
+}
+export async function createIOSWorker(onEvent: (event: WorkerEvent) => void) {
+  const { python, env } = await prepareIOSWorker()
+  let released = false
+  const worker = new DebuggerProcess(python, '', event => {
+    if (event.event === 'terminated' && ['process_exit', 'detached', 'pause_limit', 'idle_limit', 'session_limit'].includes(String(event.reason))) released = true
+    onEvent(event)
+  }, { args: ['-u', '-s', '-B', iosWorkerSource], env })
+  return new IOSWorker(worker, () => released)
+}
+/** A dead worker is not proof that its owned suspension was released. */
+export class IOSWorker implements DebugWorker {
+  private detached = false
+  constructor(private worker: DebugWorker, private released: () => boolean) {}
+  async call(command: string, args: Record<string, unknown> = {}, timeout = 10000) {
+    const result = await this.worker.call(command, args, timeout)
+    if (command === 'detach' && result.detached === true) this.detached = true
+    return result
+  }
+  async close() {
+    if (!this.detached && !this.released()) {
+      try { await this.call('detach', {}, 1000) } catch { /* Report uncertainty after bounded transport shutdown. */ }
+    }
+    await this.worker.close()
+    if (!this.detached && !this.released()) throw new DebuggerError('DEBUGGER_CLEANUP_FAILED')
+  }
+}

package/src/debugger/ios.ts

@@ -0,0 +1,45 @@
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import path from 'node:path'
+import { realpath } from 'node:fs/promises'
+import { getXcrunCmd } from '../utils/ios/utils.js'
+import type { DebugNative, DebugTarget } from './android.js'
+import { DebuggerError, debuggerRemaining, debuggerSignal, nativeError } from './worker.js'
+const exec = promisify(execFile)
+export async function iosExec(file: string, args: string[], env?: NodeJS.ProcessEnv) {
+  try { return (await exec(file, args, { timeout: debuggerRemaining(5000), signal: debuggerSignal(), maxBuffer: 1024 * 1024, ...(env ? { env } : {}) })).stdout.trim() }
+  catch (e) { throw nativeError(e, 'DEVICE_UNAVAILABLE') }
+}
+export class IOSDebugNative implements DebugNative {
+  constructor(private run = iosExec) {}
+  private sim(args: string[]) { return this.run(getXcrunCmd(), ['simctl', ...args]) }
+  async candidates(device: string, app: string): Promise<DebugTarget[]> {
+    if (!/^[A-Fa-f0-9]{8}(?:-[A-Fa-f0-9]{4}){3}-[A-Fa-f0-9]{12}$/.test(device) || !/^[A-Za-z0-9][A-Za-z0-9.-]+$/.test(app)) throw new DebuggerError('INVALID_ARGUMENT')
+    const inventory = JSON.parse(await this.sim(['list', 'devices', 'booted', '--json'])) as { devices: Record<string, { udid: string; state: string }[]> }
+    if (!Object.values(inventory.devices).flat().some(d => d.udid === device && d.state === 'Booted')) throw new DebuggerError('DEBUGGER_UNSUPPORTED')
+    const services = await this.sim(['spawn', device, 'launchctl', 'list'])
+    const pids = this.processes(services, app)
+    if (!pids.length) return []
+    const container = await this.sim(['get_app_container', device, app, 'app'])
+    const executable = await this.run('/usr/bin/plutil', ['-extract', 'CFBundleExecutable', 'raw', '-o', '-', path.join(container, 'Info.plist')])
+    if (path.basename(executable) !== executable || !executable) throw new DebuggerError('PROCESS_NOT_FOUND')
+    const executablePath = await realpath(path.join(container, executable))
+    return Promise.all(pids.map(pid => this.identity(device, { app_id: app, pid, process_name: executable, executable_path: executablePath, start_identity: '', uid: null })))
+  }
+  private processes(services: string, app: string) {
+    return services.split('\n').flatMap(line => {
+      const [pid, , label] = line.trim().split(/\s+/)
+      return /^\d+$/.test(pid) && label?.startsWith(`UIKitApplication:${app}[`) ? [Number(pid)] : []
+    })
+  }
+  async identity(device: string, target: DebugTarget): Promise<DebugTarget> {
+    const services = await this.sim(['spawn', device, 'launchctl', 'list'])
+    if (!this.processes(services, target.app_id).includes(target.pid)) throw new DebuggerError('PROCESS_CHANGED')
+    const command = await this.run('/bin/ps', ['-ww', '-p', String(target.pid), '-o', 'comm='])
+    const started = await this.run('/bin/ps', ['-p', String(target.pid), '-o', 'lstart='])
+    if (command !== target.executable_path || !started || (target.start_identity && started !== target.start_identity)) throw new DebuggerError('PROCESS_CHANGED')
+    return { ...target, start_identity: started }
+  }
+  async forward(): Promise<number> { throw new DebuggerError('DEBUGGER_UNSUPPORTED') }
+  async removeForward() { throw new DebuggerError('DEBUGGER_UNSUPPORTED') }
+}

package/{worker → src/debugger/java}/DebuggerWorker.java

@@ -139,9 +139,15 @@ public final class DebuggerWorker {
     try(Reader reader=new InputStreamReader(System.in,StandardCharsets.UTF_8)){
       StringBuilder line=new StringBuilder();int ch;
       while((ch=reader.read())!=-1){if(ch!='\n'){line.append((char)ch);if(line.length()>MAX_LINE)throw new IOException("IPC_LIMIT");continue;}
-        Object id=null;
-        try{@SuppressWarnings("unchecked") Map<String,Object>a=(Map<String,Object>)new Json(line.toString()).value();id=a.get("id");synchronized(lock){Object result=command(a);send(obj("id",id,"result",result));}}
-        catch(Exception e){String msg=e.getMessage();String code=msg!=null&&msg.matches("(?:DEBUGGER|INVALID|PROCESS|DEVICE)_[A-Z_]+")?msg:e instanceof VMDisconnectedException?"DEBUGGER_DISCONNECTED":"DEBUGGER_WORKER_FAILED";send(obj("id",id,"error",obj("code",code)));}
+        Object id=null;String commandName="";
+        try{@SuppressWarnings("unchecked") Map<String,Object>a=(Map<String,Object>)new Json(line.toString()).value();id=a.get("id");commandName=str(a,"command");synchronized(lock){Object result=command(a);send(obj("id",id,"result",result));}}
+        catch(Exception e){
+          String msg=e.getMessage();
+          String code=msg!=null&&msg.matches("(?:DEBUGGER|INVALID|PROCESS|DEVICE)_[A-Z_]+")?msg:e instanceof VMDisconnectedException?"DEBUGGER_DISCONNECTED":"DEBUGGER_WORKER_FAILED";
+          String stage=commandName.equals("attach")?"attach":e instanceof VMDisconnectedException?"transport":"command";
+          String reason=e instanceof java.net.ConnectException?"connection_refused":e instanceof VMDisconnectedException?"transport_lost":e instanceof java.net.SocketTimeoutException || e instanceof TransportTimeoutException?"timeout":"operation_failed";
+          send(obj("id",id,"error",obj("code",code,"diagnostic",obj("stage",stage,"reason",reason))));
+        }
         line.setLength(0);
       }
     }finally{synchronized(lock){finish("parent_closed");}watchdog.shutdownNow();}

package/src/debugger/lldb/breakpoints.py

@@ -0,0 +1,51 @@
+"""Owned source breakpoints with exact-line checking, including late image loads."""
+import os
+import uuid
+import lldb
+
+
+class Breakpoints:
+    def __init__(self, target):
+        self.target = target
+        self.owned = {}
+
+    def describe(self, key):
+        bp, source, line = self.owned[key]
+        locations = []
+        rejected = False
+        for loc in bp:
+            entry = loc.GetAddress().GetLineEntry()
+            actual = str(entry.GetFileSpec())
+            exact = entry.IsValid() and os.path.normpath(actual) == source and entry.GetLine() == line
+            loc.SetEnabled(exact)
+            if exact:
+                locations.append({"source_file": actual, "line": line})
+            else:
+                rejected = True
+        known_source = self.target.FindCompileUnits(lldb.SBFileSpec(source)).GetSize() > 0
+        status = "resolved" if locations else "rejected" if rejected or known_source else "pending"
+        return {"breakpoint_id": key, "status": status, "locations": locations}
+
+    def set(self, args):
+        source = os.path.normpath(args["sourceFile"])
+        bp = self.target.BreakpointCreateByLocation(lldb.SBFileSpec(source), args["line"], 0, 0, lldb.SBFileSpecList(), False)
+        key = str(uuid.uuid4())
+        self.owned[key] = (bp, source, args["line"])
+        result = self.describe(key)
+        if result["status"] == "rejected":
+            self.target.BreakpointDelete(bp.GetID())
+            del self.owned[key]
+        return result
+
+    def refresh(self):
+        return [self.describe(key) for key in list(self.owned)]
+
+    def remove(self, key):
+        if key in self.owned:
+            bp, _, _ = self.owned.pop(key)
+            self.target.BreakpointDelete(bp.GetID())
+        return {"removed": True}
+
+    def clear(self):
+        for key in list(self.owned):
+            self.remove(key)

package/src/debugger/lldb/inspection.py

@@ -0,0 +1,109 @@
+"""Bounded, static inspection. Never evaluate expressions or object descriptions."""
+import uuid
+import re
+import lldb
+
+
+def location(frame):
+    entry = frame.GetLineEntry()
+    file = entry.GetFileSpec()
+    source = str(file)[:512] if file.IsValid() else None
+    return {"source_file": source, "line": entry.GetLine() if entry.IsValid() else None,
+            "method_name": (frame.GetFunctionName() or "")[:512], "class_name": None}
+
+
+class Inspection:
+    def __init__(self):
+        self.invalidate()
+
+    def invalidate(self):
+        self.stop_id = None
+        self.threads = {}
+        self.frames = {}
+
+    def stopped(self, process):
+        self.invalidate()
+        self.stop_id = str(uuid.uuid4())
+        selected = None
+        chosen = process.GetSelectedThread()
+        threads = [chosen] if chosen.IsValid() else []
+        for index in range(min(process.GetNumThreads(), 100)):
+            thread = process.GetThreadAtIndex(index)
+            if not chosen.IsValid() or thread.GetThreadID() != chosen.GetThreadID():
+                threads.append(thread)
+        for thread in threads[:100]:
+            key = str(uuid.uuid4())
+            self.threads[key] = thread
+            if selected is None and thread.GetStopReason() not in (lldb.eStopReasonNone, lldb.eStopReasonInvalid):
+                selected = key
+        if selected is None or process.GetState() != lldb.eStateStopped:
+            self.invalidate()
+            return None
+        thread = self.threads.get(selected)
+        return {"event": "stopped", "stop_id": self.stop_id, "thread_id": selected,
+                "reason": stop_reason(thread),
+                "location": location(thread.GetFrameAtIndex(0)) if thread else None,
+                "threads": [{"thread_id": key, "name": (t.GetName() or "")[:256]} for key, t in self.threads.items()],
+                "threads_truncated": process.GetNumThreads() > 100}
+
+    def thread(self, args):
+        if args.get("stopId") != self.stop_id or args.get("threadId") not in self.threads:
+            raise ValueError("DEBUGGER_STALE_REFERENCE")
+        return self.threads[args["threadId"]]
+
+    def stack(self, args):
+        thread = self.thread(args)
+        offset, limit = args.get("offset", 0), args.get("limit", 20)
+        count = min(thread.GetNumFrames(), 1000)
+        frames = []
+        for index in range(offset, min(count, offset + limit)):
+            frame = thread.GetFrameAtIndex(index)
+            key = self.stop_id + ":" + args["threadId"] + ":" + str(index)
+            if key not in self.frames and len(self.frames) >= 1000:
+                break
+            self.frames[key] = frame
+            frames.append({"frame_id": key, "index": index, **location(frame)})
+        return {"frames": frames, "truncated": count > offset + len(frames) or thread.GetNumFrames() > 1000}
+
+    def locals(self, args):
+        if args.get("stopId") != self.stop_id or args.get("frameId") not in self.frames:
+            raise ValueError("DEBUGGER_STALE_REFERENCE")
+        frame = self.frames[args["frameId"]]
+        values = frame.GetVariables(True, True, False, True, lldb.eNoDynamicValues)
+        result = []
+        for index in range(min(values.GetSize(), 100)):
+            value = values.GetValueAtIndex(index).GetNonSyntheticValue()
+            name, kind = (value.GetName() or "")[:256], (value.GetTypeName() or "")[:256]
+            if not value.GetError().Success():
+                result.append({"name": name, "type": kind, "availability": "unavailable"})
+                continue
+            primitive = value.GetType().GetTypeFlags() & (lldb.eTypeIsScalar | lldb.eTypeIsInteger | lldb.eTypeIsFloat)
+            text = value.GetValue() if primitive else None
+            # Swift value wrappers are not C scalars. Decode only standard primitive storage.
+            if kind in ("Swift.Int", "Swift.Int32", "Swift.Int64", "Swift.UInt", "Swift.Bool", "Swift.Double", "Swift.Float"):
+                storage = value.GetChildMemberWithName("_value").GetNonSyntheticValue()
+                if storage.IsValid() and storage.GetError().Success():
+                    text = storage.GetValue()
+            if kind == "Swift.Bool" and text in ("0", "1"):
+                text = "true" if text == "1" else "false"
+            result.append({"name": name, "type": kind, "value": text[:256] if text else None,
+                           "kind": "primitive" if text is not None else "object",
+                           "truncated": bool(text and len(text) > 256),
+                           "object_id": self.object_identity(value, kind) if text is None else None})
+        return {"availability": "available" if result else "unknown", "locals": result,
+                "reason": None if result else "EMPTY_OR_UNAVAILABLE_VARIABLE_METADATA",
+                "truncated": values.GetSize() > 100}
+
+    def object_identity(self, value, kind):
+        pointer = value.GetValue()
+        if pointer and re.fullmatch(r"0x[0-9a-fA-F]+", pointer):
+            return str(uuid.uuid5(uuid.UUID(self.stop_id), kind + ":" + pointer))
+        return None
+
+
+def stop_reason(thread):
+    if thread is None:
+        return "unknown"
+    return {lldb.eStopReasonBreakpoint: "breakpoint", lldb.eStopReasonPlanComplete: "step",
+            lldb.eStopReasonSignal: "signal", lldb.eStopReasonException: "exception",
+            lldb.eStopReasonWatchpoint: "watchpoint", lldb.eStopReasonExec: "exec"}.get(thread.GetStopReason(), "unknown")

package/src/debugger/lldb/worker.py

@@ -0,0 +1,203 @@
+"""Private JSON worker for simulator LLDB. Stdout is exclusively bounded IPC."""
+import json
+import os
+import queue
+import sys
+import threading
+import time
+import lldb
+from inspection import Inspection
+from breakpoints import Breakpoints
+
+requests = queue.Queue(maxsize=64)
+output_lock = threading.Lock()
+
+
+def send(value):
+    data = json.dumps(value, separators=(",", ":"))
+    if len(data.encode()) > 1024 * 1024:
+        raise ValueError("DEBUGGER_WORKER_FAILED")
+    with output_lock:
+        sys.stdout.write(data + "\n")
+        sys.stdout.flush()
+
+
+def read_input():
+    try:
+        while True:
+            line = sys.stdin.buffer.readline(1024 * 1024 + 1)
+            if not line:
+                break
+            if len(line) > 1024 * 1024:
+                break
+            requests.put(json.loads(line), timeout=1)
+    except Exception:
+        pass
+    finally:
+        # EOF must remain observable even when the queue was filled by a dead parent.
+        eof.set()
+
+
+eof = threading.Event()
+
+
+class Worker:
+    def __init__(self):
+        self.debugger = lldb.SBDebugger.Create(False)
+        self.debugger.SetAsync(True)
+        self.debugger.SetUseColor(False)
+        lldb.SBDebugger.SetInternalVariable("target.load-script-from-symbol-file", "false", self.debugger.GetInstanceName())
+        self.output = open(os.devnull, "w")
+        self.debugger.SetOutputFileHandle(self.output, False)
+        self.debugger.SetErrorFileHandle(self.output, False)
+        self.process = None
+        self.attached = False
+        self.breakpoints = None
+        self.inspection = Inspection()
+        self.created = self.activity = time.monotonic()
+        self.paused_at = None
+        self.last_stop = 0
+        self.terminal = False
+
+    def attach(self, args):
+        self.debugger.SetAsync(False)
+        target = self.debugger.CreateTarget(args["executablePath"])
+        if not target.IsValid():
+            raise ValueError("DEBUGGER_WORKER_FAILED")
+        self.breakpoints = Breakpoints(target)
+        error = lldb.SBError()
+        self.process = target.AttachToProcessWithID(self.debugger.GetListener(), args["pid"], error)
+        self.debugger.SetAsync(True)
+        self.attached = self.process.IsValid()
+        if not error.Success() or not self.process.IsValid():
+            raise ValueError("DEBUGGER_WORKER_FAILED")
+        actual = self.process.GetProcessInfo().GetExecutableFile()
+        if not actual.IsValid() or os.path.realpath(str(actual)) != os.path.realpath(args["executablePath"]):
+            self.process.Detach()
+            raise ValueError("DEBUGGER_WORKER_FAILED")
+        self.last_stop = self.process.GetStopID()
+        if not self.process.Continue().Success():
+            raise ValueError("DEBUGGER_WORKER_FAILED")
+        return {"attached": True}
+
+    def detach(self):
+        self.inspection.invalidate()
+        if self.breakpoints:
+            self.breakpoints.clear()
+        if self.attached:
+            if not self.process.IsValid():
+                raise ValueError("DEBUGGER_WORKER_FAILED")
+            if self.process.GetState() not in (lldb.eStateExited, lldb.eStateDetached):
+                error = self.process.Detach()
+                if not error.Success():
+                    raise ValueError("DEBUGGER_WORKER_FAILED")
+            self.attached = False
+        self.terminal = True
+        return {"detached": True}
+
+    def poll(self):
+        # Removing process events updates LLDB's public state/thread snapshot.
+        # Polling GetState alone can leave the initial attach stop cached.
+        for _ in range(32):
+            event = lldb.SBEvent()
+            if not self.debugger.GetListener().GetNextEvent(event):
+                break
+            if lldb.SBProcess.EventIsProcessEvent(event):
+                lldb.SBProcess.GetStateFromEvent(event)
+        if not self.process or self.terminal:
+            return
+        state = self.process.GetState()
+        if state in (lldb.eStateExited, lldb.eStateDetached):
+            self.inspection.invalidate()
+            self.terminal = True
+            send({"event": "terminated", "reason": "process_exit" if state == lldb.eStateExited else "detached"})
+        elif state == lldb.eStateStopped and self.process.GetStopID() != self.last_stop:
+            self.breakpoints.refresh()
+            event = self.inspection.stopped(self.process)
+            if event:
+                self.last_stop = self.process.GetStopID()
+                self.paused_at = time.monotonic()
+                send(event)
+
+    def command(self, args):
+        command = args["command"]
+        if command == "attach":
+            return self.attach(args)
+        if command == "detach":
+            return self.detach()
+        if not self.process or self.terminal:
+            raise ValueError("DEBUGGER_DISCONNECTED")
+        if command in ("heartbeat", "state"):
+            return {"breakpoints": self.breakpoints.refresh()}
+        if command == "set":
+            return self.breakpoints.set(args)
+        if command == "remove":
+            return self.breakpoints.remove(args["breakpointId"])
+        if command in ("stack", "locals", "step", "resume"):
+            if args.get("stopId") != self.inspection.stop_id:
+                raise ValueError("DEBUGGER_STALE_REFERENCE")
+            if self.process.GetState() != lldb.eStateStopped:
+                raise ValueError("DEBUGGER_NOT_PAUSED")
+        if command == "stack":
+            return self.inspection.stack(args)
+        if command == "locals":
+            return self.inspection.locals(args)
+        if command in ("step", "resume"):
+            thread = self.inspection.thread(args) if command == "step" else None
+            self.inspection.invalidate()
+            self.paused_at = None
+            if command == "resume":
+                if not self.process.Continue().Success():
+                    raise ValueError("DEBUGGER_WORKER_FAILED")
+            else:
+                error = lldb.SBError()
+                if args["kind"] == "into":
+                    thread.StepInto(None, lldb.LLDB_INVALID_LINE_NUMBER, error, lldb.eOnlyDuringStepping)
+                elif args["kind"] == "over":
+                    thread.StepOver(lldb.eOnlyDuringStepping, error)
+                else:
+                    thread.StepOut(error)
+                if not error.Success():
+                    raise ValueError("DEBUGGER_WORKER_FAILED")
+            return {"resumed": True}
+        raise ValueError("INVALID_ARGUMENT")
+
+    def expired(self):
+        now = time.monotonic()
+        return ("pause_limit" if self.paused_at and now - self.paused_at >= 60 else
+                "idle_limit" if now - self.activity >= 300 else
+                "session_limit" if now - self.created >= 1800 else None)
+
+
+def main():
+    worker = Worker()
+    threading.Thread(target=read_input, daemon=True).start()
+    try:
+        while not eof.is_set():
+            worker.poll()
+            reason = worker.expired()
+            if reason:
+                worker.detach()
+                send({"event": "terminated", "reason": reason})
+                break
+            try:
+                args = requests.get(timeout=0.02)
+            except queue.Empty:
+                continue
+            worker.activity = time.monotonic()
+            try:
+                result = worker.command(args)
+                send({"id": args["id"], "result": result})
+            except Exception as error:
+                allowed = {"INVALID_ARGUMENT", "DEBUGGER_NOT_PAUSED", "DEBUGGER_STALE_REFERENCE", "DEBUGGER_DISCONNECTED"}
+                code = str(error) if isinstance(error, ValueError) and str(error) in allowed else "DEBUGGER_WORKER_FAILED"
+                send({"id": args["id"], "error": {"code": code}})
+    finally:
+        try:
+            worker.detach()
+        finally:
+            lldb.SBDebugger.Destroy(worker.debugger)
+
+
+if __name__ == "__main__":
+    main()

package/src/debugger/protocol.ts

@@ -0,0 +1,37 @@
+import { parseDiagnostic, type DebuggerDiagnostic } from './diagnostics.js'
+/** Worker messages contain private debuggee data; never include them in errors. */
+export interface WorkerEvent extends Record<string, unknown> {
+  event: string
+  reason?: string
+  diagnostic?: DebuggerDiagnostic
+  stop_id?: string
+}
+export type WorkerReply = Record<string, unknown>
+export type WorkerMessage =
+  | { kind: 'event'; value: WorkerEvent }
+  | { kind: 'reply'; id: number; result: WorkerReply; error?: { code?: string; diagnostic?: DebuggerDiagnostic } }
+
+const workerCodes = new Set(['INVALID_ARGUMENT', 'DEBUGGER_BUSY', 'DEBUGGER_NOT_FOUND', 'DEBUGGER_NOT_PAUSED', 'DEBUGGER_STALE_REFERENCE', 'DEBUGGER_DISCONNECTED', 'DEBUGGER_WORKER_FAILED'])
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+export function parseWorkerMessage(value: unknown): WorkerMessage {
+  if (!record(value)) throw new Error('INVALID_WORKER_MESSAGE')
+  if (value.event) {
+    if (typeof value.event !== 'string') throw new Error('INVALID_WORKER_EVENT')
+    for (const field of ['reason', 'stop_id']) {
+      if (value[field] !== undefined && typeof value[field] !== 'string') throw new Error('INVALID_WORKER_EVENT')
+    }
+    const event = { ...value } as WorkerEvent
+    if (value.diagnostic !== undefined) event.diagnostic = parseDiagnostic(value.diagnostic)
+    return { kind: 'event', value: event }
+  }
+  if (typeof value.id !== 'number' || !Number.isSafeInteger(value.id) || value.id < 1) throw new Error('INVALID_WORKER_REPLY')
+  if (value.error) {
+    if (!record(value.error) || (value.error.code !== undefined && typeof value.error.code !== 'string')) throw new Error('INVALID_WORKER_ERROR')
+    if (value.error.code !== undefined && !workerCodes.has(value.error.code as string)) throw new Error('INVALID_WORKER_ERROR')
+    return { kind: 'reply', id: value.id, result: {}, error: { ...(value.error.code === undefined ? {} : { code: value.error.code as string }), ...(value.error.diagnostic === undefined ? {} : { diagnostic: parseDiagnostic(value.error.diagnostic) }) } }
+  }
+  if (!record(value.result)) throw new Error('INVALID_WORKER_RESULT')
+  return { kind: 'reply', id: value.id, result: value.result }
+}