mobile-debug-mcp 0.33.0 → 0.35.0

package/src/debugger/java/DebuggerWorker.java

@@ -0,0 +1,166 @@
+import com.sun.jdi.*;
+import com.sun.jdi.connect.*;
+import com.sun.jdi.event.*;
+import com.sun.jdi.request.*;
+import java.io.*;
+import java.nio.charset.StandardCharsets;
+import java.util.*;
+import java.util.concurrent.*;
+
+/** Standalone JDI bridge. No debuggee method invocation, evaluation or mutation. */
+public final class DebuggerWorker {
+  static final int MAX_LINE = 1048576;
+  final Object lock = new Object();
+  VirtualMachine vm;
+  final Map<String, Map<String,Object>> breaks = new LinkedHashMap<>();
+  final Map<String, StackFrame> frames = new HashMap<>();
+  final Map<String, ThreadReference> threads = new HashMap<>();
+  final List<EventSet> held = new ArrayList<>();
+  String stopId;
+  long attachedAt, pausedAt, activityAt;
+  boolean closed;
+  StepRequest step;
+  final ScheduledExecutorService watchdog = Executors.newSingleThreadScheduledExecutor(r -> { Thread t=new Thread(r,"debugger-watchdog"); t.setDaemon(true); return t; });
+  static Map<String,Object> obj(Object... pairs) { Map<String,Object> m=new LinkedHashMap<>(); for(int i=0;i<pairs.length;i+=2)m.put((String)pairs[i],pairs[i+1]);return m; }
+  static synchronized void send(Object o) { System.out.println(Json.write(o)); System.out.flush(); }
+  static String str(Map<String,Object> m,String k) { Object v=m.get(k); return v==null?"":v.toString(); }
+  static int num(Map<String,Object> m,String k,int d) { Object v=m.get(k);return v instanceof Number?((Number)v).intValue():d; }
+  static RuntimeException fail(String code) { return new IllegalStateException(code); }
+  void active() { if(vm==null || closed)throw fail("DEBUGGER_DISCONNECTED"); }
+  void paused(Map<String,Object> a) { active();if(stopId==null)throw fail("DEBUGGER_NOT_PAUSED");if(!stopId.equals(str(a,"stopId")))throw fail("DEBUGGER_STALE_REFERENCE"); }
+  void invalidate() { stopId=null;frames.clear();threads.clear();pausedAt=0; }
+  void cancelStep() { if(step!=null){try{vm.eventRequestManager().deleteEventRequest(step);}catch(RuntimeException ignored){}step=null;} }
+  void release() { for(EventSet s:held)s.resume();held.clear();invalidate(); }
+  Map<String,Object> location(Location l) { String source=null;try{source=l.sourceName();}catch(AbsentInformationException ignored){}return obj("class_name",l.declaringType().name(),"method",l.method().name(),"source",source,"line",l.lineNumber(),"code_index",l.codeIndex(),"class_loader_id",l.declaringType().classLoader()==null?"bootstrap":String.valueOf(l.declaringType().classLoader().uniqueID())); }
+  String thread(ThreadReference t) { String id=stopId+":"+t.uniqueID();threads.put(id,t);return id; }
+  Map<String,Object> state() {return obj("state",closed?"detached":stopId==null?"running":"paused","stop_id",stopId,"breakpoints",new ArrayList<>(breaks.values()));}
+  void bind(Map<String,Object> b,ReferenceType type) {
+    try {
+      List<Location> ls=type.locationsOfLine(((Number)b.get("line")).intValue());
+      if(ls.isEmpty()){ if(!"verified".equals(b.get("status")))b.put("status","rejected"); b.put("reason","DEBUGGER_LOCATION_UNAVAILABLE");return; }
+      @SuppressWarnings("unchecked") List<Object> locations=(List<Object>)b.get("locations");
+      for(Location l:ls){
+        Map<String,Object> loc=location(l); if(locations.contains(loc))continue;
+        BreakpointRequest req=vm.eventRequestManager().createBreakpointRequest(l);req.putProperty("id",b.get("breakpoint_id"));req.setSuspendPolicy(EventRequest.SUSPEND_ALL);req.enable();locations.add(loc);
+      }
+      b.put("status","verified");b.remove("reason");
+    } catch(AbsentInformationException e){if(!"verified".equals(b.get("status")))b.put("status","rejected");b.put("reason","DEBUGGER_LOCATION_UNAVAILABLE");}
+  }
+  void eventLoop() {
+    try {
+      while(!closed){
+        EventSet set=vm.eventQueue().remove(200);
+        if(set==null)continue;
+        synchronized(lock){
+          if(closed)break;
+          List<Object> stops=new ArrayList<>();ThreadReference trigger=null;Set<ReferenceType> prepared=new HashSet<>();
+          for(Event event:set){
+            if(event instanceof VMDeathEvent || event instanceof VMDisconnectEvent){finish("process_exit");return;}
+            if(event instanceof ClassPrepareEvent c && prepared.add(c.referenceType())){ for(Map<String,Object>b:breaks.values())if(!"removed".equals(b.get("status")) && b.get("className").equals(c.referenceType().name())){bind(b,c.referenceType());send(obj("event","breakpoint","breakpoint",b));} }
+            if(event instanceof BreakpointEvent b){trigger=b.thread();stops.add(obj("reason","breakpoint","location",location(b.location()),"breakpoint_id",b.request().getProperty("id")));}
+            if(event instanceof StepEvent s){trigger=s.thread();stops.add(obj("reason","step","location",location(s.location())));}
+          }
+          if(!stops.isEmpty()){
+            cancelStep();held.add(set);
+            // Additional simultaneously suspended sets belong to the same epoch.
+            if(stopId==null){stopId=UUID.randomUUID().toString();pausedAt=System.nanoTime();}
+            send(obj("event","stopped","state","paused","stop_id",stopId,"thread_id",thread(trigger),"stops",stops));
+          }else set.resume();
+        }
+      }
+    }catch(InterruptedException e){Thread.currentThread().interrupt();}catch(RuntimeException e){synchronized(lock){finish("transport_lost");}}
+  }
+  void finish(String reason) {
+    if(closed)return;
+    boolean clean=true;
+    try{if(vm!=null){cancelStep();vm.dispose();}}catch(VMDisconnectedException ignored){}catch(RuntimeException e){clean=false;}
+    closed=true;held.clear();invalidate();
+    send(obj("event","terminated","reason",reason,"cleanup_complete",clean,"execution_state","unknown"));
+  }
+  Object command(Map<String,Object> a) throws Exception {
+    String cmd=str(a,"command");activityAt=System.nanoTime();
+    if(cmd.equals("attach")){
+      if(vm!=null)throw fail("DEBUGGER_BUSY");
+      AttachingConnector c=Bootstrap.virtualMachineManager().attachingConnectors().stream().filter(x->x.name().equals("com.sun.jdi.SocketAttach")).findFirst().orElseThrow();
+      Map<String,Connector.Argument> args=c.defaultArguments();args.get("hostname").setValue("127.0.0.1");args.get("port").setValue(str(a,"port"));args.get("timeout").setValue(str(a,"timeoutMs"));
+      vm=c.attach(args);attachedAt=System.nanoTime();
+      Thread t=new Thread(this::eventLoop,"debugger-events");t.setDaemon(true);t.start();
+      return state();
+    }
+    if(cmd.equals("detach")){finish("requested");return state();}
+    active();
+    if(cmd.equals("heartbeat"))return obj("alive",true);
+    if(cmd.equals("state"))return state();
+    if(cmd.equals("set")){
+      if(breaks.size()>=100)throw fail("DEBUGGER_BUSY");
+      String id=UUID.randomUUID().toString();Map<String,Object>b=obj("breakpoint_id",id,"className",str(a,"className"),"line",num(a,"line",0),"status","pending","locations",new ArrayList<>());
+      breaks.put(id,b);
+      ClassPrepareRequest req=vm.eventRequestManager().createClassPrepareRequest();req.addClassFilter(str(a,"className"));req.putProperty("id",id);req.setSuspendPolicy(EventRequest.SUSPEND_ALL);req.enable();
+      for(ReferenceType type:vm.classesByName(str(a,"className")))bind(b,type);
+      return b;
+    }
+    if(cmd.equals("remove")){
+      String id=str(a,"breakpointId");
+      if(!breaks.containsKey(id))throw fail("DEBUGGER_NOT_FOUND");
+      for(EventRequest r:new ArrayList<EventRequest>(vm.eventRequestManager().breakpointRequests()))if(id.equals(r.getProperty("id")))vm.eventRequestManager().deleteEventRequest(r);
+      for(EventRequest r:new ArrayList<EventRequest>(vm.eventRequestManager().classPrepareRequests()))if(id.equals(r.getProperty("id")))vm.eventRequestManager().deleteEventRequest(r);
+      breaks.get(id).put("status","removed");return obj("removed",true);
+    }
+    paused(a);
+    if(cmd.equals("stack")){
+      ThreadReference t=threads.get(str(a,"threadId"));if(t==null)throw fail("DEBUGGER_STALE_REFERENCE");
+      int count=Math.min(t.frameCount(),1000),offset=num(a,"offset",0),end=Math.min(count,offset+num(a,"limit",20));List<Object> out=new ArrayList<>();
+      for(int i=offset;i<end;i++){StackFrame f=t.frame(i);String id=stopId+":"+t.uniqueID()+":"+i;if(!frames.containsKey(id)&&frames.size()>=1000)throw fail("DEBUGGER_BUSY");frames.put(id,f);out.add(obj("frame_id",id,"index",i,"location",location(f.location())));}
+      return obj("frames",out,"next_offset",end<count?end:null,"truncated",t.frameCount()>1000);
+    }
+    if(cmd.equals("locals")){
+      StackFrame f=frames.get(str(a,"frameId"));if(f==null)throw fail("DEBUGGER_STALE_REFERENCE");List<Object> out=new ArrayList<>();
+      try{List<LocalVariable> vars=f.visibleVariables();if(vars.isEmpty())return obj("availability","unknown","reason","EMPTY_OR_UNAVAILABLE_VARIABLE_METADATA","locals",out,"truncated",false);for(LocalVariable v:vars.subList(0,Math.min(vars.size(),100))){Value value=f.getValue(v);Object display=null;boolean truncated=false;
+        if(value instanceof StringReference s){String text=s.value();truncated=text.length()>256;display=text.substring(0,Math.min(text.length(),256));}
+        else if(value instanceof PrimitiveValue)display=value.toString();
+        else if(value instanceof ObjectReference o)display=obj("object_id",String.valueOf(o.uniqueID()),"type",o.referenceType().name());
+        out.add(obj("name",v.name(),"type",v.typeName(),"value",display,"truncated",truncated));}
+        return obj("availability","available","locals",out,"truncated",vars.size()>100);
+      }catch(AbsentInformationException e){return obj("availability","debug_metadata_unavailable","locals",out,"truncated",false);}
+    }
+    if(cmd.equals("resume") || cmd.equals("step")){
+      if(cmd.equals("step")){
+        ThreadReference t=threads.get(str(a,"threadId"));if(t==null)throw fail("DEBUGGER_STALE_REFERENCE");cancelStep();
+        int depth=switch(str(a,"kind")){case "into"->StepRequest.STEP_INTO;case "over"->StepRequest.STEP_OVER;case "out"->StepRequest.STEP_OUT;default->throw fail("INVALID_ARGUMENT");};
+        step=vm.eventRequestManager().createStepRequest(t,StepRequest.STEP_LINE,depth);step.addCountFilter(1);step.setSuspendPolicy(EventRequest.SUSPEND_ALL);step.enable();
+      }else cancelStep();
+      release();return state();
+    }
+    throw fail("INVALID_ARGUMENT");
+  }
+  void run() throws IOException {
+    watchdog.scheduleAtFixedRate(()->{synchronized(lock){if(vm==null||closed)return;long now=System.nanoTime();String reason=pausedAt!=0&&now-pausedAt>=TimeUnit.SECONDS.toNanos(60)?"pause_limit":now-activityAt>=TimeUnit.MINUTES.toNanos(5)?"idle_limit":now-attachedAt>=TimeUnit.MINUTES.toNanos(30)?"session_limit":null;if(reason!=null)finish(reason);}},1,1,TimeUnit.SECONDS);
+    Runtime.getRuntime().addShutdownHook(new Thread(()->{synchronized(lock){finish("worker_shutdown");}}));
+    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;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();}
+  }
+  public static void main(String[] args) throws Exception {new DebuggerWorker().run();}
+
+  // Small strict JSON codec for the bounded, whitelisted bridge protocol.
+  static final class Json {
+    final String s;int p;Json(String s){this.s=s;}
+    void ws(){while(p<s.length()&&Character.isWhitespace(s.charAt(p)))p++;}
+    Object value(){Object v=read();ws();if(p!=s.length())throw fail("INVALID_ARGUMENT");return v;}
+    Object read(){ws();char c=s.charAt(p++);if(c=='"')return string();if(c=='{'){Map<String,Object>m=new LinkedHashMap<>();ws();if(s.charAt(p)=='}'){p++;return m;}do{ws();if(s.charAt(p++)!='"')throw fail("INVALID_ARGUMENT");String k=string();ws();if(s.charAt(p++)!=':')throw fail("INVALID_ARGUMENT");m.put(k,read());ws();c=s.charAt(p++);}while(c==',');if(c!='}')throw fail("INVALID_ARGUMENT");return m;}if(c=='['){List<Object>l=new ArrayList<>();ws();if(s.charAt(p)==']'){p++;return l;}do{l.add(read());ws();c=s.charAt(p++);}while(c==',');if(c!=']')throw fail("INVALID_ARGUMENT");return l;}p--;for(String lit:List.of("true","false","null"))if(s.startsWith(lit,p)){p+=lit.length();return lit.equals("null")?null:Boolean.valueOf(lit);}int start=p;while(p<s.length()&&"-+0123456789.eE".indexOf(s.charAt(p))>=0)p++;String number=s.substring(start,p);if(number.indexOf('.')<0&&number.indexOf('e')<0&&number.indexOf('E')<0)return Long.valueOf(number);return Double.valueOf(number);}
+    String string(){StringBuilder b=new StringBuilder();while(p<s.length()){char c=s.charAt(p++);if(c=='"')return b.toString();if(c=='\\'){c=s.charAt(p++);c=switch(c){case 'n'->'\n';case 'r'->'\r';case 't'->'\t';case 'b'->'\b';case 'f'->'\f';case 'u'->{char u=(char)Integer.parseInt(s.substring(p,p+4),16);p+=4;yield u;}case '"','\\','/'->c;default->throw fail("INVALID_ARGUMENT");};}else if(c<32)throw fail("INVALID_ARGUMENT");b.append(c);}throw fail("INVALID_ARGUMENT");}
+    static String write(Object o){if(o==null)return "null";if(o instanceof String s){StringBuilder b=new StringBuilder("\"");for(char c:s.toCharArray()){switch(c){case '"'->b.append("\\\"");case '\\'->b.append("\\\\");case '\n'->b.append("\\n");case '\r'->b.append("\\r");case '\t'->b.append("\\t");default->{if(c<32||Character.isSurrogate(c))b.append(String.format("\\u%04x",(int)c));else b.append(c);}}}return b.append('"').toString();}if(o instanceof Map<?,?>m){List<String>l=new ArrayList<>();m.forEach((k,v)->l.add(write(k.toString())+":"+write(v)));return "{"+String.join(",",l)+"}";}if(o instanceof Collection<?>l){List<String>a=new ArrayList<>();l.forEach(v->a.add(write(v)));return "["+String.join(",",a)+"]";}return o.toString();}
+  }
+}

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 }
+}

package/src/debugger/sessions.ts

@@ -0,0 +1,327 @@
+import { atStage, classify, diagnostic, type DebuggerDiagnostic, type DiagnosticStage } from './diagnostics.js';
+import type { WorkerReply } from './protocol.js';
+import { registerDebuggerPauseProvider } from './guard.js';
+import { randomUUID } from 'node:crypto';
+import { AndroidDebugNative, type DebugNative, type DebugTarget } from './android.js';
+import { createWorker, prepareWorker, DebuggerError, withDebuggerBudget, debuggerRemaining, type DebugWorker, type WorkerEvent } from './worker.js';
+type State = 'attaching' | 'running' | 'paused' | 'detaching' | 'detached' | 'disconnected' | 'failed';
+interface Session {
+    id: string;
+    device: string;
+    target: DebugTarget | null;
+    state: State;
+    stop: WorkerEvent | null;
+    reason: string | null;
+    diagnostic?: DebuggerDiagnostic;
+    worker?: DebugWorker;
+    port?: number;
+    queue: Promise<unknown>;
+    events: SessionEvent[];
+    sequence: number;
+    cleanup: {
+        status: 'pending' | 'complete' | 'failed';
+        remaining_resources: string[];
+    };
+    terminalAt?: number;
+    created: number;
+    activity: number;
+    pausedAt?: number;
+    timer?: ReturnType<typeof setInterval>;
+    cleaning?: Promise<void>;
+}
+interface SessionEvent extends WorkerEvent {
+    sequence: number;
+    received_at_ms: number;
+}
+type CommandArgs = Record<string, unknown> & {
+    afterSequence?: number;
+    signal?: AbortSignal;
+    stopId?: string;
+};
+interface ResultPayload {
+    success?: boolean;
+    error?: {
+        code: string | null;
+        message: string | null;
+        retryable: boolean;
+        diagnostic?: DebuggerDiagnostic;
+    };
+    events?: SessionEvent[];
+    next_cursor?: number;
+    overflow?: boolean;
+    timed_out?: boolean;
+    execution_state?: 'unknown';
+    breakpoints?: unknown;
+    result?: WorkerReply;
+}
+export const debuggerCapabilities = { attach: true, breakpoints: true, stacks: true, locals: true, step: true, resume: true,
+    evaluation: false, mutation: false, coroutines: false, native: false };
+const limitations = ['JAVA_KOTLIN_BYTECODE_ONLY', 'DEBUG_METADATA_REQUIRED', 'SHALLOW_LOCALS', 'ALL_THREADS_SUSPEND', 'DEVICE_WIDE_UI_GUARD'];
+export function debuggerExpiry(created: number, activity: number, pausedAt: number | undefined, now: number) {
+    return pausedAt !== undefined && now - pausedAt >= 60000 ? 'pause_limit' : now - activity >= 300000 ? 'idle_limit' : now - created >= 1800000 ? 'session_limit' : null;
+}
+export class DebuggerSessions {
+    private sessions = new Map<string, Session>();
+    private closing = false;
+    constructor(private native: DebugNative = new AndroidDebugNative(), private workerFactory = createWorker, private prerequisite = prepareWorker) { }
+    private prune() {
+        const terminal = [...this.sessions.values()].filter(s => s.terminalAt !== undefined && s.cleanup.status === 'complete');
+        for (const s of terminal)
+            if (Date.now() - s.terminalAt! >= 600000)
+                this.sessions.delete(s.id);
+        const remaining = terminal.filter(s => this.sessions.has(s.id));
+        for (const s of remaining.slice(0, Math.max(0, remaining.length - 100)))
+            this.sessions.delete(s.id);
+    }
+    private get(id: string) { this.prune(); const s = this.sessions.get(id); if (!s)
+        throw new DebuggerError('DEBUGGER_NOT_FOUND'); s.activity = Date.now(); return s; }
+    private serial<T>(s: Session, fn: () => Promise<T>) { const out = s.queue.then(fn); s.queue = out.catch(() => { }); return out; }
+    private result(s: Session, payload: ResultPayload = {}) {
+        const success = payload.success ?? (!['failed', 'disconnected'].includes(s.state) && s.cleanup.status !== 'failed');
+        const code = s.cleanup.status === 'failed' ? 'DEBUGGER_CLEANUP_FAILED' : s.state === 'disconnected' ? 'DEBUGGER_DISCONNECTED' : s.reason?.match(/^[A-Z_]+$/) ? s.reason : 'DEBUGGER_WORKER_FAILED';
+        return structuredClone({ success, ...(!success ? { error: { code, message: code, retryable: false, diagnostic: s.cleanup.status === 'failed' ? diagnostic('cleanup', 'operation_failed') : s.diagnostic ?? diagnostic('unknown', 'unknown') } } : {}), debug_session_id: s.id,
+            device: { platform: 'android', id: s.device }, target: s.target, state: s.state, captured_at_ms: Date.now(),
+            capabilities: debuggerCapabilities, limitations, cleanup: s.cleanup, reason: s.reason, stop: s.stop, ...payload });
+    }
+    summary(id: string) { return this.result(this.get(id)); }
+    hasActiveSessions() { return [...this.sessions.values()].some(s => s.cleanup.status !== 'complete'); }
+    paused(device: string) { const s = [...this.sessions.values()].find(s => s.device === device && s.state === 'paused'); return s ? this.result(s) : null; }
+    assertRunning(device: string) { if (this.paused(device))
+        throw new DebuggerError('DEBUGGER_PAUSED'); }
+    private event(s: Session, event: WorkerEvent) {
+        if (s.cleanup.status === 'complete')
+            return;
+        if (event.event === 'stopped' && !s.cleaning) {
+            s.state = 'paused';
+            s.stop = event;
+            s.pausedAt ??= Date.now();
+        }
+        if (event.event === 'terminated' || event.event === 'worker_failed') {
+            if (!s.cleaning) s.diagnostic ??= event.diagnostic ?? diagnostic(event.event === 'worker_failed' ? 'ipc' : 'transport', event.reason === 'transport_lost' ? 'transport_lost' : 'unknown');
+            if (!s.cleaning && s.state !== 'failed')
+                s.reason = event.reason ?? 'worker_failed';
+            if (!s.cleaning) {
+                s.state = event.event === 'worker_failed' ? 'failed' : event.reason === 'process_exit' || event.reason === 'transport_lost' ? 'disconnected' : 'detached';
+                s.stop = null;
+                // The worker has disposed or lost its transport. Cleanup remains pending until host resources are checked.
+                void this.serial(s, () => this.cleanup(s, false));
+            }
+        }
+        s.events.push({ ...event, sequence: ++s.sequence, received_at_ms: Date.now() });
+        if (s.events.length > 256)
+            s.events.shift();
+    }
+    async capabilities(device: string, app: string, pid?: number) {
+        const prerequisites: Record<string, boolean> = { jdk: false, device: false, process: false };
+        let candidates: DebugTarget[] = [];
+        const reasons: string[] = [];
+        const diagnostics: DebuggerDiagnostic[] = [];
+        try {
+            await atStage('prerequisite', 'DEBUGGER_UNSUPPORTED', () => this.prerequisite());
+            prerequisites.jdk = true;
+        }
+        catch (e) {
+            if (e instanceof DebuggerError && ['DEBUGGER_TIMEOUT', 'DEBUGGER_CANCELLED'].includes(e.code))
+                throw e;
+            reasons.push('DEBUGGER_UNSUPPORTED');
+            diagnostics.push(classify(e, 'prerequisite', 'DEBUGGER_UNSUPPORTED').diagnostic ?? diagnostic('prerequisite', 'unknown'));
+        }
+        try {
+            candidates = await atStage('target_resolution', 'DEVICE_UNAVAILABLE', () => this.native.candidates(device, app));
+            prerequisites.device = true;
+            prerequisites.process = candidates.some(t => pid === undefined || pid === t.pid);
+            if (!prerequisites.process)
+                { reasons.push('PROCESS_NOT_FOUND'); diagnostics.push(diagnostic('target_resolution', 'unavailable')); }
+        }
+        catch (e) {
+            if (e instanceof DebuggerError && ['DEBUGGER_TIMEOUT', 'DEBUGGER_CANCELLED'].includes(e.code))
+                throw e;
+            reasons.push(e instanceof DebuggerError ? e.code : 'DEVICE_UNAVAILABLE');
+            diagnostics.push(classify(e, 'target_resolution', 'DEVICE_UNAVAILABLE').diagnostic ?? diagnostic('target_resolution', 'unknown'));
+        }
+        return { success: true, debug_session_id: null, device: { platform: 'android', id: device }, target: null, state: null,
+            captured_at_ms: Date.now(), supported: Object.values(prerequisites).every(Boolean), prerequisites, candidates,
+            ...(diagnostics.length ? { diagnostics } : {}), capabilities: debuggerCapabilities, reasons, limitations, cleanup: { status: 'complete', remaining_resources: [] } };
+    }
+    async attach(device: string, app: string, pid?: number, timeout = 10000) {
+        this.prune();
+        const owned = [...this.sessions.values()].filter(s => s.cleanup.status !== 'complete');
+        if (this.closing || owned.length >= 4 || owned.some(s => s.device === device))
+            throw new DebuggerError('DEBUGGER_BUSY');
+        const s: Session = { id: randomUUID(), device, target: null, state: 'attaching', stop: null, reason: null,
+            queue: Promise.resolve(), events: [], sequence: 0, cleanup: { status: 'pending', remaining_resources: [] }, created: Date.now(), activity: Date.now() };
+        this.sessions.set(s.id, s);
+        return this.serial(s, async () => {
+            let stage: DiagnosticStage = 'prerequisite';
+            const deadline = Date.now() + timeout;
+            const remaining = () => { try { debuggerRemaining(timeout); const ms = deadline - Date.now(); if (ms <= 0)
+                throw new DebuggerError('DEBUGGER_TIMEOUT'); return ms; } catch (e) { throw classify(e, stage, 'DEBUGGER_ATTACH_FAILED'); } };
+            try {
+                await atStage('prerequisite', 'DEBUGGER_ATTACH_FAILED', () => this.prerequisite());
+                remaining();
+                stage = 'target_resolution';
+                const candidates = (await atStage('target_resolution', 'DEBUGGER_ATTACH_FAILED', () => this.native.candidates(device, app))).filter(t => pid === undefined || t.pid === pid);
+                remaining();
+                if (!candidates.length)
+                    throw new DebuggerError('PROCESS_NOT_FOUND', diagnostic('target_resolution', 'unavailable'));
+                if (candidates.length > 1)
+                    throw new DebuggerError('PROCESS_AMBIGUOUS');
+                s.target = candidates[0];
+                stage = 'forwarding';
+                s.port = await atStage('forwarding', 'DEBUGGER_ATTACH_FAILED', () => this.native.forward(device, s.target!.pid));
+                remaining();
+                s.cleanup.remaining_resources.push(`forward:tcp:${s.port}`);
+                stage = 'worker_start';
+                s.worker = await atStage('worker_start', 'DEBUGGER_ATTACH_FAILED', () => this.workerFactory(event => this.event(s, event)));
+                remaining();
+                s.cleanup.remaining_resources.push('jdi_worker');
+                stage = 'attach';
+                await atStage('attach', 'DEBUGGER_ATTACH_FAILED', () => s.worker!.call('attach', { port: s.port, timeoutMs: remaining() }, remaining()));
+                stage = 'target_resolution';
+                await atStage('target_resolution', 'DEBUGGER_ATTACH_FAILED', () => this.native.identity(device, s.target!));
+                remaining();
+                if (s.state === 'attaching')
+                    s.state = 'running';
+                if (['failed', 'disconnected', 'detached'].includes(s.state))
+                    throw new DebuggerError('DEBUGGER_ATTACH_FAILED');
+                s.timer = setInterval(() => {
+                    const now = Date.now();
+                    const reason = debuggerExpiry(s.created, s.activity, s.pausedAt, now);
+                    if (reason) {
+                        s.reason = reason;
+                        void this.serial(s, () => this.cleanup(s, true));
+                    }
+                }, 1000);
+                s.timer.unref();
+            }
+            catch (e) {
+                s.diagnostic ??= classify(e, stage, 'DEBUGGER_ATTACH_FAILED').diagnostic;
+                s.state = 'failed';
+                s.reason = e instanceof DebuggerError ? e.code : 'DEBUGGER_ATTACH_FAILED';
+                await this.cleanup(s, true);
+                return this.result(s, { success: false, error: { code: s.reason, message: s.reason, retryable: false, diagnostic: s.diagnostic } });
+            }
+            return this.result(s);
+        });
+    }
+    private async cleanup(s: Session, requestDetach: boolean): Promise<void> {
+        if (s.cleaning)
+            return s.cleaning;
+        s.cleaning = withDebuggerBudget(10000, undefined, async () => {
+            if (s.timer)
+                clearInterval(s.timer);
+            const terminal = ['failed', 'disconnected'].includes(s.state) ? s.state : 'detached';
+            s.state = 'detaching';
+            s.stop = null;
+            s.pausedAt = undefined;
+            const remaining: string[] = [];
+            if (s.worker) {
+                if (requestDetach) {
+                    try {
+                        await s.worker.call('detach', {}, 3000);
+                    }
+                    catch { /* EOF/transport closure is the fallback; execution remains unknown. */ }
+                }
+                try {
+                    await s.worker.close();
+                    s.worker = undefined;
+                }
+                catch {
+                    remaining.push('jdi_worker');
+                }
+            }
+            if (s.port !== undefined && s.target) {
+                try {
+                    await this.native.removeForward(s.device, s.port, s.target.pid);
+                    s.port = undefined;
+                }
+                catch {
+                    remaining.push(`forward:tcp:${s.port}`);
+                }
+            }
+            s.events = [];
+            s.cleanup = { status: remaining.length ? 'failed' : 'complete', remaining_resources: remaining };
+            s.state = terminal;
+            s.terminalAt = Date.now();
+        });
+        try {
+            await s.cleaning;
+        }
+        finally {
+            s.cleaning = undefined;
+        }
+    }
+    async command(id: string, command: string, args: CommandArgs = {}, timeout = 10000) {
+        const s = this.get(id);
+        if (command === 'events') {
+            const deadline = Date.now() + timeout;
+            const after = args.afterSequence ?? 0;
+            if (after > s.sequence)
+                throw new DebuggerError('INVALID_ARGUMENT');
+            if (args.signal?.aborted)
+                throw new DebuggerError('DEBUGGER_CANCELLED', diagnostic('command', 'cancelled'));
+            if (s.worker && ['running', 'paused'].includes(s.state))
+                await atStage('command', 'DEBUGGER_WORKER_FAILED', () => s.worker!.call('heartbeat', {}, Math.min(timeout, 1000)));
+            while (Date.now() < deadline && !s.events.some(e => e.sequence > after) && s.cleanup.status === 'pending') {
+                if (args.signal?.aborted)
+                    throw new DebuggerError('DEBUGGER_CANCELLED', diagnostic('command', 'cancelled'));
+                await new Promise(resolve => setTimeout(resolve, Math.min(50, deadline - Date.now())));
+            }
+            const events = s.events.filter(e => e.sequence > after).slice(0, 100);
+            return this.result(s, { events, next_cursor: events.at(-1)?.sequence ?? s.sequence, overflow: after < (s.events[0]?.sequence ?? s.sequence + 1) - 1, timed_out: events.length === 0 });
+        }
+        return this.serial(s, () => this.executeCommand(s, command, args, timeout));
+    }
+    private assertCommandTarget(s: Session, command: string, args: CommandArgs) {
+        if (!s.worker || ['detaching', 'detached', 'disconnected', 'failed'].includes(s.state))
+            throw new DebuggerError('DEBUGGER_DISCONNECTED', s.diagnostic ?? diagnostic('command', 'unavailable'));
+        if (['stack', 'locals', 'step', 'resume'].includes(command)) {
+            if (args.stopId !== s.stop?.stop_id)
+                throw new DebuggerError('DEBUGGER_STALE_REFERENCE');
+            if (s.state !== 'paused')
+                throw new DebuggerError('DEBUGGER_NOT_PAUSED');
+        }
+    }
+    private async executeCommand(s: Session, command: string, args: CommandArgs, timeout: number) {
+        if (command === 'detach') {
+            if (s.cleanup.status !== 'complete')
+                await this.cleanup(s, true);
+            return this.result(s, { success: s.cleanup.status === 'complete', execution_state: 'unknown' });
+        }
+        if (command === 'state' && (s.cleanup.status === 'complete' || ['detaching', 'detached', 'disconnected', 'failed'].includes(s.state)))
+            return this.result(s);
+        this.assertCommandTarget(s, command, args);
+        if (command === 'step' || command === 'resume') {
+            s.state = 'running';
+            s.stop = null;
+            s.pausedAt = undefined;
+        }
+        try {
+            const data = await s.worker!.call(command, args, timeout);
+            return this.result(s, command === 'state' ? { breakpoints: data.breakpoints } : { result: data });
+        }
+        catch (e) {
+            return this.handleCommandError(s, command, classify(e, 'command', 'DEBUGGER_WORKER_FAILED'));
+        }
+    }
+    private async handleCommandError(s: Session, command: string, e: unknown) {
+        if (e instanceof DebuggerError && e.code === 'DEBUGGER_DISCONNECTED') {
+            s.diagnostic ??= e.diagnostic ?? diagnostic('transport', 'transport_lost');
+            s.state = 'disconnected';
+            s.reason = 'transport_lost';
+            await this.cleanup(s, false);
+            if (command === 'state')
+                return this.result(s);
+        }
+        if ((command === 'step' || command === 'resume' || command === 'set' || command === 'remove') && e instanceof DebuggerError && ['DEBUGGER_TIMEOUT', 'DEBUGGER_CANCELLED', 'DEBUGGER_WORKER_FAILED'].includes(e.code)) {
+            s.diagnostic ??= e.diagnostic;
+            s.state = 'failed';
+            s.reason = e.code;
+            await this.cleanup(s, true);
+        }
+        throw e;
+    }
+    async shutdown() { this.closing = true; await Promise.allSettled([...this.sessions.values()].filter(s => s.cleanup.status !== 'complete').map(s => this.serial(s, () => this.cleanup(s, true)))); return [...this.sessions.values()].filter(s => s.cleanup.status !== 'complete').map(s => this.result(s)); }
+}
+export const debuggerSessions = new DebuggerSessions();
+registerDebuggerPauseProvider(device => debuggerSessions.paused(device));