Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(browser): advertise zero-based units for runtime source coordinates (#1085)
Kaoru08226218d289e241
diff --git a/docs/web-runtime.md b/docs/web-runtime.mdindex d98d1f6f1..76c05752c 100644--- a/docs/web-runtime.md+++ b/docs/web-runtime.md@@ -20,7 +20,9 @@ Results retain:- The selected target, frame and document loader identity; local armed/end timestamps and separate backend monotonic coverage timestamps.- Every admitted producer function/block range, exclusive end offset and execution count in UTF-16 code units, with verified bounds when exact text is available. Nested/overlapping counts are preserved and must not be summed.- Main-document script inventory, exact session script IDs, resource start coordinates, sourceURL/source-map declarations, producer hash and independently computed UTF-8 text digest.-- Armed-window requests from the selected main frame and selected origins, complete reported initiator objects (including stack hierarchy/descriptions), derived callsites, exact script-ID associations and unresolved async parent IDs. Source association does not establish UI causality.+- Armed-window requests from the selected main frame and selected origins, complete reported initiator objects (including stack hierarchy/descriptions), derived callsites, exact script-ID associations and unresolved async parent IDs. Source association does not establish UI causality. Callsite and listener `line_number`/`column_number` values are CDP's zero-based lines and UTF-16 columns in the script's enclosing resource: the script file for an external script, or the HTML document for an inline script. `resource_start` is where the script text starts in that resource. `trace_web_source_location` takes one-based, script-relative lines and zero-based UTF-16 columns.++For an external script, use `line = line_number + 1` and keep `column = column_number`. For an inline script, use `line = line_number - resource_start.line_number + 1`. Subtract `resource_start.column_number` from `column_number` only when `line_number === resource_start.line_number`; keep the reported column on later lines. Columns remain zero-based. This conversion requires known source-start and column coordinates; preserve unavailable coordinates as unknown.The coverage counter interval starts at backend acceptance before the armed receipt and ends at the resetting sample after the local timer. Counts may include execution during these command intervals; request events are restricted to the locally armed window. The result retains both backend timestamps and the distinct local clock.diff --git a/src/domain/webRuntime.test.ts b/src/domain/webRuntime.test.tsnew file mode 100644index 000000000..0b8666d03--- /dev/null+++ b/src/domain/webRuntime.test.ts@@ -0,0 +1,34 @@+import { describe, expect, it } from "vitest";+import { z } from "zod";++import {+ webRuntimeLocationSchema,+ webRuntimeSourceSchema,+} from "./webRuntime.js";++const properties = (schema: z.ZodType) =>+ z+ .object({ properties: z.record(z.string(), z.unknown()) })+ .parse(z.toJSONSchema(schema, { io: "output" })).properties;++describe("web runtime coordinate contract", () => {+ it("advertises zero-based resource-relative CDP lines and UTF-16 columns", () => {+ const location = properties(webRuntimeLocationSchema);+ expect(location.line_number).toMatchObject({+ description: expect.stringContaining(+ "Zero-based line in the script's enclosing resource",+ ),+ });+ expect(location.column_number).toMatchObject({+ description: expect.stringContaining("Zero-based UTF-16 column"),+ });+ const start = properties(+ webRuntimeSourceSchema.shape.resource_start.unwrap(),+ );+ expect(start.line_number).toMatchObject({+ description: expect.stringContaining(+ "Zero-based line where the script text starts",+ ),+ });+ });+});diff --git a/src/domain/webRuntime.ts b/src/domain/webRuntime.tsindex c06c0d29b..0cab1e171 100644--- a/src/domain/webRuntime.ts+++ b/src/domain/webRuntime.ts@@ -6,6 +6,20 @@ import {import { browserVersionSchema } from "./browserObservationSchemas.js";import { jsonObjectSchema } from "./jsonValue.js";+// CDP positions are zero-based and relative to the script's enclosing+// resource: the script file for an external script, or the HTML document for+// an inline script. trace_web_source_location takes one-based,+// script-relative lines, so the advertised units keep callers from passing a+// position off by one or by the inline script's offset.+const RESOURCE_LINE =+ "Zero-based line in the script's enclosing resource (the script file for an external script, or the HTML document for an inline script), as reported by CDP.";+const RESOURCE_COLUMN =+ "Zero-based UTF-16 column on that line of the enclosing resource, as reported by CDP.";+const START_LINE =+ "Zero-based line where the script text starts in its enclosing resource (the HTML document for an inline script).";+const START_COLUMN =+ "Zero-based UTF-16 column where the script text starts on that line of its enclosing resource.";+/** Scope for one externally owned page; omitted origins select its current origin. */export const webRuntimeScopeSchema = z.strictObject({cdp_endpoint: browserEndpointSchema,@@ -27,8 +41,8 @@ export const webRuntimeSourceSchema = z.object({language: z.string().nullable(),resource_start: z.object({- line_number: z.number().int().min(0),- column_number: z.number().int().min(0),+ line_number: z.number().int().min(0).describe(START_LINE),+ column_number: z.number().int().min(0).describe(START_COLUMN),}).nullable(),source: z.discriminatedUnion("state", [@@ -51,8 +65,8 @@ export type WebRuntimeSource = z.infer<typeof webRuntimeSourceSchema>;export const webRuntimeLocationSchema = z.object({script_id: z.string(),url: z.string().nullable(),- line_number: z.number().int().min(0),- column_number: z.number().int().min(0).nullable(),+ line_number: z.number().int().min(0).describe(RESOURCE_LINE),+ column_number: z.number().int().min(0).nullable().describe(RESOURCE_COLUMN),function_name: z.string().nullable(),source_association: z.enum(["script_id", "unknown"]),});