@kenkaiiii/ggcoder 5.69.0 → 5.71.0

package/dist/core/node-debugger.d.ts

@@ -0,0 +1,148 @@
+import { type SandboxPolicy } from "./sandbox.js";
+import { type ToolOperations } from "../tools/operations.js";
+/**
+ * A live Node.js debugging session driven over the V8 inspector protocol
+ * (Chrome DevTools Protocol). The program runs under `node --inspect-brk`
+ * bound to loopback on a random port; this class connects, sets breakpoints,
+ * steps, and reads real runtime state — so the agent can see the value that
+ * broke instead of guessing from source and print-and-rerun loops.
+ *
+ * Node only, no new dependency: Node 22+ ships both the inspector and a global
+ * WebSocket. `.ts` files work when run by Node's own type stripping, which
+ * keeps line numbers; loaders that transpile (tsx, ts-node) shift lines.
+ */
+export type PauseOnExceptions = "none" | "uncaught" | "all";
+export interface DebugLaunchOptions {
+    cwd: string;
+    program: string;
+    args?: readonly string[];
+    nodeArgs?: readonly string[];
+    pauseOnExceptions?: PauseOnExceptions;
+    breakpoints?: ReadonlyArray<{
+        file: string;
+        line: number;
+        condition?: string;
+    }>;
+    sandboxPolicy?: SandboxPolicy;
+    ops?: ToolOperations;
+    /** How long to wait for the inspector to come up. */
+    startTimeoutMs?: number;
+}
+export type StopState = {
+    kind: "paused";
+} | {
+    kind: "exited";
+    code: number | null;
+} | {
+    kind: "running";
+};
+interface RemoteObject {
+    type: string;
+    subtype?: string;
+    className?: string;
+    value?: unknown;
+    unserializableValue?: string;
+    description?: string;
+    objectId?: string;
+    preview?: ObjectPreview;
+}
+interface ObjectPreview {
+    type: string;
+    subtype?: string;
+    description?: string;
+    overflow: boolean;
+    properties: Array<{
+        name: string;
+        type: string;
+        value?: string;
+        subtype?: string;
+    }>;
+    entries?: Array<{
+        key?: ObjectPreview;
+        value: ObjectPreview;
+    }>;
+}
+interface Breakpoint {
+    id: string;
+    /** The URL-pattern breakpoint first, then one per script bound by exact URL. */
+    cdpIds: string[];
+    /** The pattern the first CDP breakpoint was set with. */
+    urlRegex: string;
+    /** The target file, comparable with `samePath`. */
+    target: string;
+    /** As the caller wrote it, for display. */
+    file: string;
+    line: number;
+    condition?: string;
+    boundLines: number[];
+}
+/** One-line rendering of a value the inspector returned. */
+export declare function formatRemoteObject(object: RemoteObject): string;
+/** File path for an inspector script URL, or undefined for node: internals and evals. */
+export declare function urlToPath(url: string): string | undefined;
+export declare class NodeDebugSession {
+    /** The cwd as the program was launched in it. */
+    private readonly launchCwd;
+    /** `launchCwd` fully resolved, for displaying paths relative to it. */
+    private readonly cwd;
+    private readonly child;
+    private readonly socket;
+    private readonly pending;
+    private readonly scripts;
+    private readonly breakpoints;
+    private readonly stopWaiters;
+    /** In-flight exact-URL breakpoint bindings (see `bindToScript`). */
+    private readonly binding;
+    private nextMessageId;
+    private nextBreakpoint;
+    private paused;
+    private exitCode;
+    private output;
+    private outputDropped;
+    private outputRead;
+    private constructor();
+    /** Start `node --inspect-brk <program>`, attach, set breakpoints, run to the first stop. */
+    static launch(options: DebugLaunchOptions): Promise<NodeDebugSession>;
+    private connect;
+    private initialize;
+    private onMessage;
+    private send;
+    private appendOutput;
+    private markExited;
+    private wakeStopWaiters;
+    get isPaused(): boolean;
+    get hasExited(): boolean;
+    state(): StopState;
+    /** Wait until the program pauses or exits, up to `timeoutMs`. */
+    waitForStop(timeoutMs: number, signal?: AbortSignal): Promise<StopState>;
+    /** Resume (or step) and wait for the next stop. */
+    resume(how: "continue" | "step_over" | "step_into" | "step_out", timeoutMs: number, signal?: AbortSignal): Promise<StopState>;
+    pause(timeoutMs: number, signal?: AbortSignal): Promise<StopState>;
+    setBreakpoint(file: string, line: number, condition?: string): Promise<Breakpoint>;
+    /**
+     * Also bind `bp` by the exact URL of a loaded script that is the target file
+     * but that the URL pattern missed — Node can name a script in a spelling no
+     * path form predicts (Windows short names, drive-letter case, URL encoding).
+     * The file itself, resolved on disk, decides whether it is the same script.
+     */
+    private bindToScript;
+    removeBreakpoint(id: string): Promise<boolean>;
+    listBreakpoints(): Breakpoint[];
+    private frame;
+    private frameLocation;
+    /** `#0 parseUser (src/user.ts:12:5)` lines, innermost first. */
+    stack(limit?: number): string;
+    /** Source lines around a frame's position, the current line marked. */
+    sourceSnippet(index?: number, context?: number): string;
+    /** Visible variables of a frame, scope by scope, innermost first. */
+    variables(index?: number): Promise<string>;
+    /** Evaluate in a paused frame, or in the global context while running. */
+    evaluate(expression: string, index?: number): Promise<string>;
+    /** Why and where the program is paused. */
+    pauseSummary(): string;
+    /** Program output since the last call. */
+    readNewOutput(): string;
+    /** Kill the program and close the connection. Safe to call twice. */
+    stop(): void;
+}
+export {};