feat(browser): retain compact scenario summaries and selected views (#7120)
Retain complete browser scenario Evidence while delivering compact summaries and selected step, event, transaction and text views through shared CLI/MCP workflows. Preserve initial CLI failures across cleanup retries and validate with real Chromium/TodoMVC. Co-authored-by: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
19 files changed
+2297
-90
No files matched your search
@@ -0,0 +1,521 @@
|
||||
import { createHash } from "node:crypto";
|
||||
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import {
|
||||
SCENARIO_ORIGIN,
|
||||
scenarioCaptureEvidence,
|
||||
scenarioCaptureFixture,
|
||||
} from "../../../tests/fixtures/browserScenarioCapture.js";
|
||||
import { inspectAnalysisView } from "./AnalysisViewService.js";
|
||||
import { projectAnalysisError } from "../../domain/analysisErrorProjection.js";
|
||||
import { sanitizeBrowserUrl } from "../../domain/browserObservation.js";
|
||||
import type { BrowserScenarioCapture } from "../../domain/browserScenarioCapture.js";
|
||||
import type { AnalysisViewRequest } from "../../domain/analysisView/analysisView.js";
|
||||
import { projectBrowserScenarioView } from "../../domain/analysisView/browserScenarioView.js";
|
||||
|
||||
const tree = (text: string) => ({
|
||||
state: "captured" as const,
|
||||
value: {
|
||||
sha256: createHash("sha256").update(text).digest("hex"),
|
||||
bytes: Buffer.byteLength(text),
|
||||
text,
|
||||
},
|
||||
});
|
||||
|
||||
/** Three steps: navigate to /quiz, capture its tree, then fail on a missing control. */
|
||||
const quizCapture = (
|
||||
thirdStep: "failed" | "completed" = "failed",
|
||||
): BrowserScenarioCapture => {
|
||||
const base = scenarioCaptureFixture();
|
||||
const [initial, browse] = base.steps;
|
||||
if (initial === undefined || browse === undefined)
|
||||
throw new Error("Fixture lacks steps");
|
||||
const quiz = sanitizeBrowserUrl(`${SCENARIO_ORIGIN}/quiz`);
|
||||
return {
|
||||
...base,
|
||||
scenario: { ...base.scenario, action_count: 2 },
|
||||
steps: [
|
||||
{
|
||||
...initial,
|
||||
artifacts: {
|
||||
...initial.artifacts,
|
||||
url: { state: "captured", value: initial.after_url },
|
||||
},
|
||||
},
|
||||
{
|
||||
...browse,
|
||||
after_url: quiz,
|
||||
artifacts: {
|
||||
...browse.artifacts,
|
||||
accessibility: tree('- heading "Question 1"'),
|
||||
screenshot: { state: "missing", reason: "page closed" },
|
||||
},
|
||||
},
|
||||
{
|
||||
...browse,
|
||||
step_index: 2,
|
||||
step_id: "answer",
|
||||
action: "click",
|
||||
before_url: quiz,
|
||||
after_url: quiz,
|
||||
...(thirdStep === "failed"
|
||||
? { status: "failed" as const, error: "locator not found" }
|
||||
: { status: "completed" as const, error: null }),
|
||||
},
|
||||
],
|
||||
};
|
||||
};
|
||||
|
||||
const view = async (
|
||||
capture: BrowserScenarioCapture,
|
||||
request: AnalysisViewRequest,
|
||||
) => {
|
||||
const projected = await inspectAnalysisView({
|
||||
source: { kind: "inline", evidence: scenarioCaptureEvidence(capture) },
|
||||
view: request,
|
||||
});
|
||||
if (!projected.ok) throw projected.error;
|
||||
return projected.value.normalized_result as Record<string, unknown>;
|
||||
};
|
||||
|
||||
describe("browser scenario analysis views", () => {
|
||||
it("counts inherited Evidence limitations alongside capture-local caveats", async () => {
|
||||
const capture = scenarioCaptureFixture();
|
||||
expect(capture.limitations).toEqual([]);
|
||||
const summary = await view(capture, { kind: "summary" });
|
||||
expect(summary).toMatchObject({
|
||||
limitations: [
|
||||
"Artifact identity is unavailable for this observation.",
|
||||
"Browser host platform and architecture were not observed.",
|
||||
],
|
||||
summary: { limitation_count: 2 },
|
||||
});
|
||||
});
|
||||
|
||||
it("summarizes steps compactly and focuses the first failing step's nearest captured tree", async () => {
|
||||
const summary = await view(quizCapture(), { kind: "summary" });
|
||||
expect(summary).toMatchObject({
|
||||
kind: "summary",
|
||||
parent_operation: "capture_browser_scenario",
|
||||
artifact: null,
|
||||
coverage: { status: "complete-within-view", exhausted: true },
|
||||
});
|
||||
const { steps, final_accessibility, network, events } =
|
||||
summary.summary as Record<string, unknown> & {
|
||||
steps: Record<string, unknown>[];
|
||||
};
|
||||
// before_url repeats only across a discontinuity; not_requested sections are omitted.
|
||||
expect(steps[0]).toHaveProperty("before_url");
|
||||
expect(steps[1]).not.toHaveProperty("before_url");
|
||||
expect(steps[2]).not.toHaveProperty("before_url");
|
||||
expect(steps[0]?.sections).toEqual({
|
||||
captured: ["url"],
|
||||
missing: [],
|
||||
truncated: [],
|
||||
});
|
||||
expect(steps[1]?.sections).toEqual({
|
||||
captured: ["accessibility"],
|
||||
missing: ["screenshot"],
|
||||
truncated: [],
|
||||
});
|
||||
expect(steps[2]).toMatchObject({
|
||||
status: "failed",
|
||||
error: "locator not found",
|
||||
after_url: { url: `${SCENARIO_ORIGIN}/quiz` },
|
||||
});
|
||||
expect(final_accessibility).toEqual({
|
||||
focus_step_index: 2,
|
||||
focus: "first-unsuccessful-step",
|
||||
step_index: 1,
|
||||
accessibility: tree('- heading "Question 1"'),
|
||||
});
|
||||
expect(network).toEqual({
|
||||
selected: true,
|
||||
transactions: 8,
|
||||
without_request: 0,
|
||||
ambiguous_transactions: 0,
|
||||
failed_transactions: 1,
|
||||
by_origin: [{ origin: SCENARIO_ORIGIN, transactions: 8 }],
|
||||
by_resource_type: [
|
||||
{ resource_type: "document", transactions: 1 },
|
||||
{ resource_type: "fetch", transactions: 7 },
|
||||
],
|
||||
by_status_class: [
|
||||
{ status_class: "2xx", transactions: 7 },
|
||||
{ status_class: "failed", transactions: 1 },
|
||||
],
|
||||
});
|
||||
expect(events).toMatchObject({ retained: 24, dropped: 0 });
|
||||
});
|
||||
|
||||
it("reports the last step's own state when no step captured a tree", async () => {
|
||||
const capture = scenarioCaptureFixture();
|
||||
expect(await view(capture, { kind: "summary" })).toMatchObject({
|
||||
summary: {
|
||||
final_accessibility: {
|
||||
focus_step_index: 1,
|
||||
focus: "last-step",
|
||||
step_index: null,
|
||||
accessibility: { state: "not_requested" },
|
||||
},
|
||||
},
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe("browser scenario analysis view pages", () => {
|
||||
it("pages exact steps with only the selected captured sections", async () => {
|
||||
const page = await view(quizCapture("completed"), {
|
||||
kind: "browser-scenario",
|
||||
collection: "steps",
|
||||
step_indices: [1, 2],
|
||||
artifacts: ["accessibility"],
|
||||
offset: 0,
|
||||
limit: 1,
|
||||
});
|
||||
expect(page).toMatchObject({
|
||||
kind: "browser-scenario",
|
||||
source_completeness: { status: "complete" },
|
||||
source_events: { retained: 24, dropped: 0 },
|
||||
coverage: { status: "page", examined: 1, total: 2, next_offset: 1 },
|
||||
items: {
|
||||
collection: "steps",
|
||||
rows: [
|
||||
{
|
||||
step_index: 1,
|
||||
artifacts: { accessibility: tree('- heading "Question 1"') },
|
||||
omitted_artifacts: [{ section: "screenshot", state: "missing" }],
|
||||
},
|
||||
],
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
it("filters events by step, kind and transaction, keeping original item indices", async () => {
|
||||
const capture = scenarioCaptureFixture();
|
||||
const responses = (await view(capture, {
|
||||
kind: "browser-scenario",
|
||||
collection: "events",
|
||||
event_kinds: ["response", "request-failed"],
|
||||
transaction_ids: ["request-2", "request-8"],
|
||||
offset: 0,
|
||||
limit: 64,
|
||||
})) as { items: { rows: { item_index: number; event: unknown }[] } };
|
||||
expect(
|
||||
responses.items.rows.map(({ item_index, event }) => ({
|
||||
item_index,
|
||||
event,
|
||||
})),
|
||||
).toEqual(
|
||||
capture.events.items.flatMap((event, item_index) =>
|
||||
(event.kind === "response" || event.kind === "request-failed") &&
|
||||
["request-2", "request-8"].includes(event.transaction_id)
|
||||
? [{ item_index, event }]
|
||||
: [],
|
||||
),
|
||||
);
|
||||
expect(responses.items.rows).toHaveLength(2);
|
||||
for (const empty of [
|
||||
{ step_indices: [] },
|
||||
{ event_kinds: [] },
|
||||
{ transaction_ids: [] },
|
||||
{ step_indices: [0] },
|
||||
])
|
||||
expect(
|
||||
await view(capture, {
|
||||
kind: "browser-scenario",
|
||||
collection: "events",
|
||||
offset: 0,
|
||||
limit: 64,
|
||||
...empty,
|
||||
}),
|
||||
).toMatchObject({
|
||||
items: { rows: [] },
|
||||
coverage: { status: "empty", total: 0, exhausted: true },
|
||||
});
|
||||
});
|
||||
|
||||
it("states dropped events and refuses views of other parents", async () => {
|
||||
const base = scenarioCaptureFixture();
|
||||
const dropped = {
|
||||
...base,
|
||||
events: {
|
||||
...base.events,
|
||||
dropped: 3,
|
||||
omissions: {
|
||||
...base.events.omissions,
|
||||
by_kind: [
|
||||
{
|
||||
kind: "console" as const,
|
||||
count: 3,
|
||||
reasons: ["max-events" as const],
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
completeness: {
|
||||
status: "truncated" as const,
|
||||
equality_eligible: false as const,
|
||||
missing_sections: [],
|
||||
truncated_sections: ["events" as const],
|
||||
},
|
||||
};
|
||||
const summary = await view(dropped, { kind: "summary" });
|
||||
expect(summary.unknowns).toContain(
|
||||
"3 events were dropped by capture budgets; counts and pages cover retained events only.",
|
||||
);
|
||||
expect(summary).toMatchObject({
|
||||
summary: {
|
||||
events: {
|
||||
dropped: 3,
|
||||
omissions: {
|
||||
by_kind: [{ kind: "console", count: 3 }],
|
||||
network_transactions: 0,
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
const refused = await inspectAnalysisView({
|
||||
source: { kind: "inline", evidence: scenarioCaptureEvidence() },
|
||||
view: { kind: "go", collection: "dependencies" },
|
||||
});
|
||||
if (refused.ok) throw new Error("Expected an unsupported view refusal");
|
||||
expect(projectAnalysisError(refused.error)).toMatchObject({
|
||||
code: "invalid_request",
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe("browser scenario retained boundaries", () => {
|
||||
it("counts transactions whose request event was omitted and keeps source omissions on an exhausted page", async () => {
|
||||
const base = scenarioCaptureFixture();
|
||||
const omitted = (
|
||||
event: BrowserScenarioCapture["events"]["items"][number],
|
||||
) =>
|
||||
event.kind === "request" ||
|
||||
(event.kind === "network-content" && event.phase === "request");
|
||||
const removed = base.events.items.filter(omitted);
|
||||
const items = base.events.items.filter((event) => !omitted(event));
|
||||
const capture: BrowserScenarioCapture = {
|
||||
...base,
|
||||
events: {
|
||||
...base.events,
|
||||
items,
|
||||
retained: items.length,
|
||||
dropped: removed.length,
|
||||
omissions: {
|
||||
...base.events.omissions,
|
||||
by_kind: [
|
||||
{ kind: "request", count: 8, reasons: ["max-events"] },
|
||||
{ kind: "network-content", count: 1, reasons: ["max-events"] },
|
||||
],
|
||||
},
|
||||
},
|
||||
completeness: {
|
||||
status: "truncated",
|
||||
equality_eligible: false,
|
||||
missing_sections: [],
|
||||
truncated_sections: ["events"],
|
||||
},
|
||||
};
|
||||
expect(await view(capture, { kind: "summary" })).toMatchObject({
|
||||
summary: {
|
||||
network: {
|
||||
transactions: 8,
|
||||
without_request: 8,
|
||||
failed_transactions: 1,
|
||||
},
|
||||
},
|
||||
});
|
||||
expect(
|
||||
await view(capture, {
|
||||
kind: "browser-scenario",
|
||||
collection: "transactions",
|
||||
transaction_ids: ["request-8"],
|
||||
event_kinds: [],
|
||||
offset: 0,
|
||||
limit: 1,
|
||||
}),
|
||||
).toMatchObject({
|
||||
source_completeness: { status: "truncated" },
|
||||
source_events: { dropped: 9 },
|
||||
coverage: { total: 1, exhausted: true },
|
||||
items: {
|
||||
rows: [
|
||||
{
|
||||
transaction_id: "request-8",
|
||||
events: [],
|
||||
omitted_events: [{ kind: "request-failed" }],
|
||||
},
|
||||
],
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
it("keeps network bodies opt-in while retaining each transaction's event identities", async () => {
|
||||
const capture = scenarioCaptureFixture();
|
||||
const request = {
|
||||
kind: "browser-scenario" as const,
|
||||
collection: "transactions" as const,
|
||||
transaction_ids: ["request-2"],
|
||||
offset: 0,
|
||||
limit: 1,
|
||||
};
|
||||
// Parse defaults at the public boundary rather than supplying a manually normalized request.
|
||||
const page = await inspectAnalysisView({
|
||||
source: { kind: "inline", evidence: scenarioCaptureEvidence(capture) },
|
||||
view: request,
|
||||
});
|
||||
if (!page.ok) throw page.error;
|
||||
const result = page.value.normalized_result;
|
||||
expect(result).toMatchObject({
|
||||
items: {
|
||||
collection: "transactions",
|
||||
rows: [{ transaction_id: "request-2" }],
|
||||
},
|
||||
});
|
||||
expect(JSON.stringify(result)).not.toContain('"content":');
|
||||
const selected = await view(capture, {
|
||||
...request,
|
||||
event_kinds: ["network-content"],
|
||||
});
|
||||
expect(JSON.stringify(selected)).toContain('"content":');
|
||||
expect(selected).toMatchObject({
|
||||
items: {
|
||||
rows: [
|
||||
{
|
||||
omitted_events: expect.arrayContaining([
|
||||
{ item_index: expect.any(Number), kind: "request" },
|
||||
]),
|
||||
},
|
||||
],
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
it("distinguishes unrequested and legacy-unknown network observation from an observed empty inventory", () => {
|
||||
const base = scenarioCaptureFixture([], {
|
||||
request_body: false,
|
||||
response_body: false,
|
||||
header_values: false,
|
||||
});
|
||||
const project = (capture: unknown) => {
|
||||
const result = projectBrowserScenarioView(
|
||||
{
|
||||
evidenceId: `ev:${"a".repeat(64)}`,
|
||||
operation: "capture_browser_scenario",
|
||||
normalizedResult: capture,
|
||||
limitations: [],
|
||||
},
|
||||
{ kind: "summary" },
|
||||
);
|
||||
if (!result.ok) throw result.error;
|
||||
return result.value;
|
||||
};
|
||||
expect(project(base)).toMatchObject({
|
||||
summary: { network: { selected: true, transactions: 0 } },
|
||||
});
|
||||
expect(
|
||||
project({ ...base, scenario: { ...base.scenario, event_families: [] } }),
|
||||
).toMatchObject({
|
||||
summary: { network: { selected: false, transactions: null } },
|
||||
});
|
||||
const { event_families: _families, ...legacyScenario } = base.scenario;
|
||||
expect(project({ ...base, scenario: legacyScenario })).toMatchObject({
|
||||
summary: { network: { selected: null, transactions: null } },
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe("browser scenario text and selection boundaries", () => {
|
||||
it("pages exact Unicode text with the full artifact digest and reports unavailable text explicitly", async () => {
|
||||
const capture = quizCapture("completed");
|
||||
const step = capture.steps[1]!;
|
||||
step.artifacts.accessibility = tree("A💡B\nC");
|
||||
const request = {
|
||||
kind: "browser-scenario" as const,
|
||||
collection: "text" as const,
|
||||
step_index: 1,
|
||||
artifact: "accessibility" as const,
|
||||
offset: 1,
|
||||
limit: 2,
|
||||
};
|
||||
expect(await view(capture, request)).toMatchObject({
|
||||
items: {
|
||||
state: "captured",
|
||||
text: "💡",
|
||||
sha256: tree("A💡B\nC").value.sha256,
|
||||
bytes: Buffer.byteLength("A💡B\nC"),
|
||||
},
|
||||
coverage: { examined: 2, total: 6, next_offset: 3 },
|
||||
});
|
||||
expect(await view(capture, { ...request, offset: 99 })).toMatchObject({
|
||||
items: { text: "" },
|
||||
coverage: { status: "empty", total: 6, exhausted: true },
|
||||
});
|
||||
expect(await view(capture, { ...request, step_index: 0 })).toMatchObject({
|
||||
items: { state: "not_requested", text: null, sha256: null, bytes: null },
|
||||
});
|
||||
});
|
||||
|
||||
it("rejects irrelevant selection fields and nonexistent text steps with typed diagnostics", async () => {
|
||||
for (const request of [
|
||||
{ kind: "browser-scenario", collection: "events", artifacts: [] },
|
||||
{
|
||||
kind: "browser-scenario",
|
||||
collection: "text",
|
||||
step_index: 99,
|
||||
artifact: "dom",
|
||||
},
|
||||
]) {
|
||||
const result = await inspectAnalysisView({
|
||||
source: { kind: "inline", evidence: scenarioCaptureEvidence() },
|
||||
view: request,
|
||||
});
|
||||
if (result.ok)
|
||||
throw new Error("Expected the invalid view to be rejected");
|
||||
expect(projectAnalysisError(result.error)).toMatchObject({
|
||||
code: "invalid_request",
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
it("keeps source truncation facts when a text page has no retained payload", async () => {
|
||||
const capture = quizCapture("completed");
|
||||
const completeness = {
|
||||
status: "truncated" as const,
|
||||
equality_eligible: false as const,
|
||||
missing_sections: [],
|
||||
truncated_sections: ["accessibility" as const],
|
||||
};
|
||||
capture.steps[1]!.artifacts.accessibility = {
|
||||
state: "truncated",
|
||||
observed: 1000,
|
||||
retained: 0,
|
||||
reason: "capture budget",
|
||||
};
|
||||
capture.steps[1]!.completeness = completeness;
|
||||
capture.completeness = completeness;
|
||||
expect(
|
||||
await view(capture, {
|
||||
kind: "browser-scenario",
|
||||
collection: "text",
|
||||
step_index: 1,
|
||||
artifact: "accessibility",
|
||||
offset: 0,
|
||||
limit: 20,
|
||||
}),
|
||||
).toMatchObject({
|
||||
source_completeness: { status: "truncated" },
|
||||
items: {
|
||||
state: "truncated",
|
||||
observed: 1000,
|
||||
retained: 0,
|
||||
reason: "capture budget",
|
||||
text: null,
|
||||
},
|
||||
coverage: { status: "empty", exhausted: true },
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -76,15 +76,15 @@ describe("environment manifests from capture_browser_scenario parents", () => {
|
||||
kind: "inline",
|
||||
evidence: scenarioCaptureEvidence(scenarioCaptureFixture()),
|
||||
},
|
||||
view: { kind: "summary" },
|
||||
view: { kind: "dart-aot", collection: "package_uris" },
|
||||
});
|
||||
if (refused.ok) throw new Error("Expected the unsupported view refusal");
|
||||
expect(projectAnalysisError(refused.error)).toMatchObject({
|
||||
code: "unsupported_target",
|
||||
message: expect.stringContaining(
|
||||
"supports only the environment-manifest, environment-state and environment-coverage views",
|
||||
),
|
||||
code: "invalid_request",
|
||||
});
|
||||
expect(JSON.stringify(projectAnalysisError(refused.error))).toContain(
|
||||
"supports summary and browser-scenario views",
|
||||
);
|
||||
});
|
||||
|
||||
it("serves and exports a scenario-built manifest from the same capture", () => {
|
||||
|
||||
@@ -21,6 +21,7 @@ export const finishAnalysisCommand = async <
|
||||
canonicalOperation: string,
|
||||
signal: AbortSignal,
|
||||
fallbackResource?: string,
|
||||
options: { readonly failureProjection?: "initial" | "final" } = {},
|
||||
): Promise<Value | ReturnType<typeof projectAnalysisError>> => {
|
||||
let result: Result<Value, AnalysisError>;
|
||||
let cleanup: AnalysisError | undefined;
|
||||
@@ -35,6 +36,12 @@ export const finishAnalysisCommand = async <
|
||||
: new ProviderAdapterError(providerId, canonicalOperation, { cause }),
|
||||
};
|
||||
}
|
||||
// Some one-shot commands promise the original failure snapshot even when
|
||||
// close retries and mutates the producer's live cleanup status.
|
||||
const initialFailure =
|
||||
!result.ok && options.failureProjection === "initial"
|
||||
? projectAnalysisError(result.error)
|
||||
: undefined;
|
||||
try {
|
||||
// Resource owners may resolve their retained errors during close. This
|
||||
// adapter cannot infer resolution of a producer's earlier cleanup failure.
|
||||
@@ -61,6 +68,7 @@ export const finishAnalysisCommand = async <
|
||||
}
|
||||
}
|
||||
await dispatchQueuedInterrupts();
|
||||
if (initialFailure !== undefined) return initialFailure;
|
||||
if (result.ok && signal.aborted)
|
||||
result = {
|
||||
ok: false,
|
||||
|
||||
@@ -2,15 +2,17 @@ import { Cli } from "incur";
|
||||
import { z } from "zod";
|
||||
|
||||
import { captureBrowserScenario } from "./application/BrowserScenarioCaptureService.js";
|
||||
import { finishAnalysisCommand } from "./cli/finishAnalysisCommand.js";
|
||||
import { withCommandCancellation } from "./cli/commandCancellation.js";
|
||||
import {
|
||||
analysisEvidenceDeliveryOptions,
|
||||
cliEvidenceDeliveryInputError,
|
||||
publishCliAnalysisEvidence,
|
||||
} from "./cli/analysisEvidenceDelivery.js";
|
||||
import { CLI_COMMANDS } from "./cliCommandNames.js";
|
||||
import { parseCliJsonInput, resolveCliJsonPaths } from "./cliJsonInput.js";
|
||||
import { logCliCommand } from "./cliLogging.js";
|
||||
import { projectAnalysisError } from "./domain/analysisErrorProjection.js";
|
||||
import {
|
||||
BrowserObservationError,
|
||||
browserCleanupObservation,
|
||||
} from "./domain/browserObservationError.js";
|
||||
import { analysisInputErrorFromIssues } from "./domain/inputIssueProjection.js";
|
||||
import { browserScenarioSchema } from "./domain/browserScenario.js";
|
||||
import type { BrowserScenarioCapturePort } from "./application/BrowserScenarioCapturePort.js";
|
||||
@@ -38,9 +40,16 @@ export const registerBrowserScenarioCommands = (
|
||||
.string()
|
||||
.describe("Inline browser scenario JSON or JSON file path"),
|
||||
}),
|
||||
run: ({ args }) =>
|
||||
options: z.object(analysisEvidenceDeliveryOptions),
|
||||
run: ({ args, options: delivery }) =>
|
||||
withCommandCancellation((signal) =>
|
||||
logCliCommand(logger, CLI_COMMANDS.captureBrowserScenario, async () => {
|
||||
const deliveryError = cliEvidenceDeliveryInputError({
|
||||
detail: delivery.detail,
|
||||
evidenceOutput: delivery.evidence_output,
|
||||
operation: OPERATION,
|
||||
});
|
||||
if (deliveryError !== undefined) return cliError(deliveryError);
|
||||
const input = await parseCliJsonInput(
|
||||
args.inputJson,
|
||||
OPERATION,
|
||||
@@ -67,28 +76,28 @@ export const registerBrowserScenarioCommands = (
|
||||
createBrowserScenarioProvider(environment),
|
||||
)
|
||||
: options.createProvider(environment);
|
||||
let result:
|
||||
| Awaited<ReturnType<typeof captureBrowserScenario>>
|
||||
| undefined;
|
||||
try {
|
||||
result = await captureBrowserScenario(provider, scenario.data, {
|
||||
signal,
|
||||
});
|
||||
return result.ok ? result.value : cliError(result.error);
|
||||
} finally {
|
||||
try {
|
||||
await provider?.close?.();
|
||||
} catch (cause: unknown) {
|
||||
// Failed captures already retain their primary error and partial
|
||||
// observations. A cleanup retry must not replace that outcome.
|
||||
if (result?.ok)
|
||||
throw new BrowserObservationError(OPERATION, "cleanup_failed", {
|
||||
cause,
|
||||
cleanup: browserCleanupObservation(cause),
|
||||
partialObservation: result.value,
|
||||
});
|
||||
}
|
||||
}
|
||||
const result = await finishAnalysisCommand(
|
||||
() => captureBrowserScenario(provider, scenario.data, { signal }),
|
||||
{
|
||||
close: async () => {
|
||||
await provider?.close?.();
|
||||
},
|
||||
},
|
||||
"rea-playwright-browser-scenario",
|
||||
OPERATION,
|
||||
signal,
|
||||
undefined,
|
||||
{ failureProjection: "initial" },
|
||||
);
|
||||
if (!("evidence_id" in result))
|
||||
return { error: "Browser scenario capture failed", ...result };
|
||||
return publishCliAnalysisEvidence(result, {
|
||||
providerId: "rea-playwright-browser-scenario",
|
||||
operation: OPERATION,
|
||||
signal,
|
||||
detail: delivery.detail,
|
||||
evidenceOutput: delivery.evidence_output,
|
||||
});
|
||||
}),
|
||||
),
|
||||
});
|
||||
|
||||
@@ -17,7 +17,7 @@ export const ANALYSIS_VIEW_TOOL_CONTRACTS = [
|
||||
...toolContractMetadata("inspect_analysis_view"),
|
||||
kind: "application",
|
||||
description:
|
||||
'Use javascript-routes collections to query route patterns, source-linked occurrences, source status, unknowns or summary counts from retained JavaScript application or web-bundle Evidence. Inspect selected views of supported completed Evidence without repeating analysis. Choose a view compatible with the parent operation described below. Command summary views preserve ordered GDB records or opaque objdump stdout/stderr once, source parameters, completion facts and parent identity. They do not establish current target state. Historical capture summaries return identity and counts without bodies or archive inventories. Capture views page retained records: view {kind: "capture", detail: "preview" | "complete", offset: 0, limit: 20}; preview selects recorded headline fields and binary descriptors, complete returns exact records with all sidecars. Offsets follow the selected parent record order, preserving original producer ordinals. Paging never reopens the source or reruns the decoder. Native export tables use kind native-exports, collection exports/issues, exact names or original indices, selected fields and matching-row pagination; parent Evidence plus source_index identifies each row. Source coverage stays separate from page coverage. BEAM views use kind beam, collections atoms/exports/imports/lambdas/chunks, exact names/indices/fields and matching-row pages; import modules intersects function names. source_index identifies original parent-and-collection rows, preserving every arity and raw atom index. beam.counts preserves null missing tables versus decoded empty tables; runtime absence remains unknown. PYC views use kind python-pyc, collection code_objects, names/indices/fields and paging; source_index scopes every same-name alternative to the parent, nested_code keeps code-constant references, and pyc.coverage preserves source coverage. Go metadata uses kind go, collection dependencies/settings, exact paths/keys or indices, fields and pagination. Row index refers to the original collection; empty selections return no rows, and dependency coverage remains unknown. Rust metadata uses kind rust, collection packages/edges, exact names/versions or original indices, selected fields, edge from_indices/to_indices and matching-row pagination. Embedded-record coverage is separate from unknown runtime dependencies. For inspect_pcap_capture parents, kind pcap pages endpoints, dns-queries, tls-sni, protocols, http-uris or unattributed-addresses. Select an exact query for dns-addresses, or a tshark/capinfos stream for UTF-16 diagnostics text. Page totals count retained facts; source coverage remains explicit. Qlog summaries keep profile/scope and counts; kind qlog pages traces, streams, loss-declarations, incomplete-records, contributions, ranges or final-sizes. Except traces, select trace_index; stream-specific facets also require exact stream_id and direction. Facts retain all-recorded-events-before-selection scope, and interval overlap or endpoint loss declarations do not prove retransmission or network loss. The api-surface view groups retained HAR requests by method, origin and format-rule path template; templated segments are inferences. It reads no headers or bodies and reports no query values. The environment-manifest view projects the same HAR requests on the primary origin (most JSON-like records) into a replayable tool surface: view {kind: "environment-manifest", template_rules: ["after-uid-literal", "opaque-token", "sibling-variance"], include_query_parameter_names: true}. Each tool has a deterministic name, a path template and parameters from the four format rules plus the selected opt-in rules, observed query parameter names, a value-free body shape for POST/PUT/PATCH, status and content-type sets and record ordinals; records are pointers into the parent, excluded groups carry a reason and three fixed unknowns are always stated. Templates, parameters and names are inferences; the view copies no header, cookie or body values and refuses parents inspected with sensitive values. A capture_browser_scenario parent that selected response bodies or header values projects the same way, one record per network transaction in request order; it relies on capture-time redaction of declared secrets instead of that refusal, and a transaction whose URL was redacted is left unrepresented. The environment-state view extracts, from the same parents, the initial state the recorded reads observed: view {kind: "environment-state", template_rules: [...]} with the rules of the manifest it accompanies. It reads response bodies recorded before the first related write and reports entity types with an identity field (proved by a path parameter or inferred from a field name), entities in collection order with per-view values where views differ, documents for non-parameterized reads that are not entities and have one initial request line (item-shaped paths stay recorded), and a render plan per read tool: item and list views rLine truncated
|
||||
'Use javascript-routes collections to query route patterns, source-linked occurrences, source status, unknowns or summary counts from retained JavaScript application or web-bundle Evidence. Inspect selected views of supported completed Evidence without repeating analysis. Choose a view compatible with the parent operation described below. Command summary views preserve ordered GDB records or opaque objdump stdout/stderr once, source parameters, completion facts and parent identity. They do not establish current target state. Historical capture summaries return identity and counts without bodies or archive inventories. Capture views page retained records: view {kind: "capture", detail: "preview" | "complete", offset: 0, limit: 20}; preview selects recorded headline fields and binary descriptors, complete returns exact records with all sidecars. Offsets follow the selected parent record order, preserving original producer ordinals. Paging never reopens the source or reruns the decoder. Native export tables use kind native-exports, collection exports/issues, exact names or original indices, selected fields and matching-row pagination; parent Evidence plus source_index identifies each row. Source coverage stays separate from page coverage. BEAM views use kind beam, collections atoms/exports/imports/lambdas/chunks, exact names/indices/fields and matching-row pages; import modules intersects function names. source_index identifies original parent-and-collection rows, preserving every arity and raw atom index. beam.counts preserves null missing tables versus decoded empty tables; runtime absence remains unknown. PYC views use kind python-pyc, collection code_objects, names/indices/fields and paging; source_index scopes every same-name alternative to the parent, nested_code keeps code-constant references, and pyc.coverage preserves source coverage. Go metadata uses kind go, collection dependencies/settings, exact paths/keys or indices, fields and pagination. Row index refers to the original collection; empty selections return no rows, and dependency coverage remains unknown. Rust metadata uses kind rust, collection packages/edges, exact names/versions or original indices, selected fields, edge from_indices/to_indices and matching-row pagination. Embedded-record coverage is separate from unknown runtime dependencies. For inspect_pcap_capture parents, kind pcap pages endpoints, dns-queries, tls-sni, protocols, http-uris or unattributed-addresses. Select an exact query for dns-addresses, or a tshark/capinfos stream for UTF-16 diagnostics text. Page totals count retained facts; source coverage remains explicit. Qlog summaries keep profile/scope and counts; kind qlog pages traces, streams, loss-declarations, incomplete-records, contributions, ranges or final-sizes. Except traces, select trace_index; stream-specific facets also require exact stream_id and direction. Facts retain all-recorded-events-before-selection scope, and interval overlap or endpoint loss declarations do not prove retransmission or network loss. The api-surface view groups retained HAR requests by method, origin and format-rule path template; templated segments are inferences. It reads no headers or bodies and reports no query values. The environment-manifest view projects the same HAR requests on the primary origin (most JSON-like records) into a replayable tool surface: view {kind: "environment-manifest", template_rules: ["after-uid-literal", "opaque-token", "sibling-variance"], include_query_parameter_names: true}. Each tool has a deterministic name, a path template and parameters from the four format rules plus the selected opt-in rules, observed query parameter names, a value-free body shape for POST/PUT/PATCH, status and content-type sets and record ordinals; records are pointers into the parent, excluded groups carry a reason and three fixed unknowns are always stated. Templates, parameters and names are inferences; the view copies no header, cookie or body values and refuses parents inspected with sensitive values. A capture_browser_scenario parent also supports summary and browser-scenario steps/events/transactions/text pages, preserving step_indices, event_kinds, transaction_ids and selected artifacts. A capture_browser_scenario parent that selected response bodies or header values projects the same way, one record per network transaction in request order; it relies on capture-time redaction of declared secrets instead of that refusal, and a transaction whose URL was redacted is left unrepresented. The environment-state view extracts, from the same parents, the initial state the recorded reads observed: view {kind: "environment-state", template_rules: [...]} with the rules of the manifest it accompanies. It reads response bodies recorded before the first related write and reports entity types with an identity field (proved by a path parameter or inferred from a field name), entities in collection order with per-view values where viewLine truncated
|
||||
inputSchema: inspectAnalysisViewInputSchema,
|
||||
outputSchema: evidenceResultOf(analysisViewResultSchema),
|
||||
examples: [
|
||||
|
||||
@@ -1,6 +1,10 @@
|
||||
import type { ToolContract } from "./toolContractTypes.js";
|
||||
import { toolContractMetadata } from "./toolEffects.js";
|
||||
import { evidenceResultOf } from "./toolOutputSchemaPrimitives.js";
|
||||
import {
|
||||
analysisDetailOutputSchemaOf,
|
||||
analysisDetailSchema,
|
||||
} from "./analysisDetail.js";
|
||||
import { browserScenarioSummaryViewResultSchema } from "../domain/analysisView/analysisView.js";
|
||||
import { browserScenarioInputSchema } from "../domain/browserScenario.js";
|
||||
import { browserScenarioCaptureSchema } from "../domain/browserScenarioCapture.js";
|
||||
import type { JsonValue } from "../domain/jsonValue.js";
|
||||
@@ -26,10 +30,15 @@ export const BROWSER_SCENARIO_TOOL_CONTRACTS = [
|
||||
name: "capture_browser_scenario",
|
||||
...toolContractMetadata("capture_browser_scenario"),
|
||||
description:
|
||||
"Run a controlled browser scenario when passive observation cannot exercise the application. Launch the selected executable or connect to a loopback CDP target, provide a start URL and actions, and select storage or artifacts when needed. A request action sends one HTTP request to the start origin through the page's own fetch, with header values from secrets, page cookies or local storage; write methods change application state. Environment, empty storage, a URL-only final capture, and measured event-retention budgets are defaults. capture.network selects request_body, response_body, and header_values independently; capture.limits lets callers raise or lower the event count, retained-allocation estimates, network transaction count, and network content budgets. Selected content is returned inline with transaction and event references, byte digests, and explicit unavailable states. Budget omissions identify affected event kinds and network transactions. Credentials and declared secrets are redacted. Agents can run their own local fixture servers to control application responses. Actions run until completion or cancellation unless timeout_ms is set. Results are returned inline.",
|
||||
"Run a controlled browser scenario when passive observation cannot exercise the application. Launch the selected executable or connect to a loopback CDP target, provide a start URL and actions, and select storage or artifacts when needed. A request action sends one HTTP request to the start origin through the page's own fetch, with header values from secrets, page cookies or local storage; write methods change application state. Environment, empty storage, a URL-only final capture, and measured event-retention budgets are defaults. capture.network selects request_body, response_body, and header_values independently; capture.limits lets callers raise or lower the event count, retained-allocation estimates, network transaction count, and network content budgets. Selected content is returned inline with transaction and event references, byte digests, and explicit unavailable states. Budget omissions identify affected event kinds and network transactions. Credentials and declared secrets are redacted. Agents can run their own local fixture servers to control application responses. Actions run until completion or cancellation unless timeout_ms is set. Default detail complete returns the capture inline. Detail summary retains complete Evidence and returns step outcomes, the final or first unsuccessful step’s accessibility tree, and event/network counts. Read exact steps with selected artifacts, UTF-16 text pages, transactions with opt-in content, or events filtered by step, kind and transaction, through inspect_analysis_view kind browser-scenario.",
|
||||
kind: "browser-provider",
|
||||
inputSchema: browserScenarioInputSchema,
|
||||
outputSchema: evidenceResultOf(browserScenarioCaptureSchema),
|
||||
inputSchema: browserScenarioInputSchema.extend({
|
||||
detail: analysisDetailSchema,
|
||||
}),
|
||||
outputSchema: analysisDetailOutputSchemaOf(
|
||||
browserScenarioCaptureSchema,
|
||||
browserScenarioSummaryViewResultSchema,
|
||||
),
|
||||
examples: [
|
||||
{ title: "Capture a deterministic browser scenario", input: example },
|
||||
],
|
||||
|
||||
@@ -122,6 +122,13 @@ import {
|
||||
|
||||
import { absoluteLocalPathStringSchema } from "../localPath.js";
|
||||
import { z } from "zod";
|
||||
import {
|
||||
browserScenarioSummarySchema,
|
||||
browserScenarioViewContextSchema,
|
||||
browserScenarioViewItemsSchema,
|
||||
browserScenarioViewRequestSchema,
|
||||
} from "./browserScenarioViewSchemas.js";
|
||||
import { projectBrowserScenarioView } from "./browserScenarioView.js";
|
||||
import {
|
||||
desktopViewRequestSchema,
|
||||
desktopViewItemsSchema,
|
||||
@@ -393,6 +400,7 @@ export const analysisViewRequestSchema = z.discriminatedUnion("kind", [
|
||||
environmentStateViewRequestSchema,
|
||||
environmentCoverageViewRequestSchema,
|
||||
captureViewRequestSchema,
|
||||
browserScenarioViewRequestSchema,
|
||||
protobufViewRequestSchema,
|
||||
qlogViewRequestSchema,
|
||||
pcapViewRequestSchema,
|
||||
@@ -729,6 +737,14 @@ export const webNetworkCaptureSummaryViewResultSchema = z.strictObject({
|
||||
summary: captureSummarySchema,
|
||||
});
|
||||
|
||||
/** Compact outcomes and the focus screen from a retained browser scenario. */
|
||||
export const browserScenarioSummaryViewResultSchema = z.strictObject({
|
||||
...summaryViewResultBase,
|
||||
artifact: z.null(),
|
||||
parent_operation: z.literal("capture_browser_scenario"),
|
||||
summary: browserScenarioSummarySchema,
|
||||
});
|
||||
|
||||
/** Exact package declarations with retained decoded manifest text. */
|
||||
export const androidPackageSummaryViewResultSchema = z.strictObject({
|
||||
...summaryViewResultBase,
|
||||
@@ -1022,6 +1038,7 @@ export const analysisViewResultSchema = z.discriminatedUnion("kind", [
|
||||
managedArtifactSummaryViewResultSchema,
|
||||
managedMemberSummaryViewResultSchema,
|
||||
webNetworkCaptureSummaryViewResultSchema,
|
||||
browserScenarioSummaryViewResultSchema,
|
||||
androidPackageSummaryViewResultSchema,
|
||||
pcapCaptureSummaryViewResultSchema,
|
||||
dartAotSummaryViewResultSchema,
|
||||
@@ -1076,6 +1093,15 @@ export const analysisViewResultSchema = z.discriminatedUnion("kind", [
|
||||
...viewResultBase,
|
||||
parent_operation: z.literal("inspect_web_network_capture"),
|
||||
}),
|
||||
z.strictObject({
|
||||
kind: z.literal("browser-scenario"),
|
||||
view: browserScenarioViewRequestSchema,
|
||||
items: browserScenarioViewItemsSchema,
|
||||
...viewResultBase,
|
||||
...browserScenarioViewContextSchema.shape,
|
||||
artifact: z.null(),
|
||||
parent_operation: z.literal("capture_browser_scenario"),
|
||||
}),
|
||||
z.strictObject({
|
||||
kind: z.literal("qlog"),
|
||||
view: qlogViewRequestSchema,
|
||||
@@ -1283,9 +1309,7 @@ const unsupportedParent = (
|
||||
new AnalysisUnsupportedTargetError(
|
||||
INSPECT_ANALYSIS_VIEW_OPERATION,
|
||||
parentArtifactPath(parent),
|
||||
parent.operation === "capture_browser_scenario"
|
||||
? `Parent Evidence operation "capture_browser_scenario" supports only the environment-manifest, environment-state and environment-coverage views.`
|
||||
: `Parent Evidence operation ${JSON.stringify(parent.operation)} does not support analysis views. Use completed Evidence from a supported parent operation with a compatible view. For a summary receipt, use its normalized_result.parent_evidence_id rather than the receipt's own evidence_id.`,
|
||||
`Parent Evidence operation ${JSON.stringify(parent.operation)} does not support analysis views. Use completed Evidence from a supported parent operation with a compatible view. For a summary receipt, use its normalized_result.parent_evidence_id rather than the receipt's own evidence_id.`,
|
||||
);
|
||||
|
||||
const parentArtifactPath = (parent: AnalysisViewParent): string => {
|
||||
@@ -1331,6 +1355,7 @@ const retainedViewProjectors = new Map<string, typeof projectWasmArtifactView>([
|
||||
["inspect_managed_artifact", projectManagedArtifactView],
|
||||
["inspect_managed_members", projectManagedMemberView],
|
||||
["inspect_android_package", projectAndroidPackageView],
|
||||
["capture_browser_scenario", projectBrowserScenarioView],
|
||||
["inspect_dart_aot", projectDartAotView],
|
||||
["inspect_il2cpp_metadata", projectIl2cppMetadataView],
|
||||
["inspect_apk_signature", projectApkSignatureView],
|
||||
|
||||
@@ -0,0 +1,193 @@
|
||||
import { z } from "zod";
|
||||
import type { RetainedBrowserScenarioCapture } from "../browserScenarioCapture.js";
|
||||
import { isImmutableJsonSnapshot } from "../immutableJson.js";
|
||||
import { compareAsciiStrings } from "../canonicalOrdering.js";
|
||||
|
||||
const count = z.int().nonnegative();
|
||||
const statusClass = z.enum([
|
||||
"1xx",
|
||||
"2xx",
|
||||
"3xx",
|
||||
"4xx",
|
||||
"5xx",
|
||||
"failed",
|
||||
"unknown",
|
||||
]);
|
||||
|
||||
/** Counts concern retained transaction identities, including those without a request event. */
|
||||
export const browserScenarioNetworkSummarySchema = z.strictObject({
|
||||
selected: z.boolean().nullable(),
|
||||
transactions: count.nullable(),
|
||||
without_request: count,
|
||||
ambiguous_transactions: count,
|
||||
failed_transactions: count,
|
||||
by_origin: z.array(
|
||||
z.strictObject({ origin: z.string().nullable(), transactions: count }),
|
||||
),
|
||||
by_resource_type: z.array(
|
||||
z.strictObject({
|
||||
resource_type: z.string().nullable(),
|
||||
transactions: count,
|
||||
}),
|
||||
),
|
||||
by_status_class: z.array(
|
||||
z.strictObject({ status_class: statusClass, transactions: count }),
|
||||
),
|
||||
});
|
||||
|
||||
interface TransactionGroup {
|
||||
readonly transaction_id: string;
|
||||
readonly source_item_indices: readonly number[];
|
||||
readonly origin: string | null;
|
||||
readonly resource_type: string | null;
|
||||
readonly status_class: z.infer<typeof statusClass>;
|
||||
readonly has_request: boolean;
|
||||
readonly failed: boolean;
|
||||
readonly ambiguous: boolean;
|
||||
}
|
||||
|
||||
interface TransactionFacts {
|
||||
indices: number[];
|
||||
origins: Set<string | null>;
|
||||
resourceTypes: Set<string>;
|
||||
statuses: Set<number>;
|
||||
requests: number;
|
||||
failed: boolean;
|
||||
}
|
||||
|
||||
/** Sealed historical captures own this metadata-only index until their retained lifetime ends. */
|
||||
const transactionsByCapture = new WeakMap<
|
||||
object,
|
||||
readonly TransactionGroup[]
|
||||
>();
|
||||
|
||||
/** Keep all observed alternatives; one missing event never erases its transaction. */
|
||||
export const browserScenarioTransactionGroups = (
|
||||
capture: RetainedBrowserScenarioCapture,
|
||||
): readonly TransactionGroup[] => {
|
||||
const reusable = isImmutableJsonSnapshot(capture);
|
||||
const known = reusable ? transactionsByCapture.get(capture) : undefined;
|
||||
if (known !== undefined) return known;
|
||||
const groups = new Map<string, TransactionFacts>();
|
||||
for (const [index, event] of capture.events.items.entries()) {
|
||||
if (!("transaction_id" in event)) continue;
|
||||
let group = groups.get(event.transaction_id);
|
||||
if (group === undefined) {
|
||||
group = {
|
||||
indices: [],
|
||||
origins: new Set(),
|
||||
resourceTypes: new Set(),
|
||||
statuses: new Set(),
|
||||
requests: 0,
|
||||
failed: false,
|
||||
};
|
||||
groups.set(event.transaction_id, group);
|
||||
}
|
||||
group.indices.push(index);
|
||||
if (event.kind === "network-content") continue;
|
||||
group.origins.add(event.url.origin);
|
||||
group.resourceTypes.add(event.resource_type);
|
||||
if (event.kind === "request") group.requests += 1;
|
||||
if (event.kind === "response") group.statuses.add(event.status);
|
||||
if (event.kind === "request-failed") group.failed = true;
|
||||
}
|
||||
const result = [...groups].map(
|
||||
([transaction_id, group]): TransactionGroup => {
|
||||
const status = group.statuses.values().next().value;
|
||||
return Object.freeze({
|
||||
transaction_id,
|
||||
source_item_indices: Object.freeze(group.indices),
|
||||
origin:
|
||||
group.origins.size === 1
|
||||
? (group.origins.values().next().value ?? null)
|
||||
: null,
|
||||
resource_type:
|
||||
group.resourceTypes.size === 1
|
||||
? (group.resourceTypes.values().next().value ?? null)
|
||||
: null,
|
||||
status_class:
|
||||
group.statuses.size === 1 && status !== undefined
|
||||
? (`${String(Math.floor(status / 100))}xx` as z.infer<
|
||||
typeof statusClass
|
||||
>)
|
||||
: group.statuses.size === 0 && group.failed
|
||||
? "failed"
|
||||
: "unknown",
|
||||
has_request: group.requests > 0,
|
||||
failed: group.failed,
|
||||
ambiguous:
|
||||
group.requests > 1 ||
|
||||
group.statuses.size > 1 ||
|
||||
group.origins.size > 1 ||
|
||||
group.resourceTypes.size > 1,
|
||||
});
|
||||
},
|
||||
);
|
||||
if (reusable) transactionsByCapture.set(capture, result);
|
||||
return result;
|
||||
};
|
||||
|
||||
const increment = <Key>(values: Map<Key, number>, key: Key): void => {
|
||||
values.set(key, (values.get(key) ?? 0) + 1);
|
||||
};
|
||||
const sorted = <Key extends string | null>(
|
||||
values: ReadonlyMap<Key, number>,
|
||||
): [Key, number][] =>
|
||||
[...values].sort(([left], [right]) =>
|
||||
left === right
|
||||
? 0
|
||||
: left === null
|
||||
? -1
|
||||
: right === null
|
||||
? 1
|
||||
: compareAsciiStrings(left, right),
|
||||
);
|
||||
|
||||
/** Null selection/counts preserve legacy unknowns and unrequested network observation. */
|
||||
export const summarizeBrowserScenarioNetwork = (
|
||||
capture: RetainedBrowserScenarioCapture,
|
||||
): z.infer<typeof browserScenarioNetworkSummarySchema> => {
|
||||
const groups = browserScenarioTransactionGroups(capture);
|
||||
const contentSelected = Object.values(capture.scenario.network_content).some(
|
||||
Boolean,
|
||||
);
|
||||
const selected =
|
||||
contentSelected ||
|
||||
capture.scenario.event_families?.includes("network") === true
|
||||
? true
|
||||
: capture.scenario.event_families === undefined
|
||||
? null
|
||||
: false;
|
||||
const origins = new Map<string | null, number>();
|
||||
const resources = new Map<string | null, number>();
|
||||
const statuses = new Map<z.infer<typeof statusClass>, number>();
|
||||
let withoutRequest = 0;
|
||||
let ambiguous = 0;
|
||||
let failed = 0;
|
||||
for (const group of groups) {
|
||||
if (!group.has_request) withoutRequest += 1;
|
||||
if (group.ambiguous) ambiguous += 1;
|
||||
if (group.failed) failed += 1;
|
||||
increment(origins, group.origin);
|
||||
increment(resources, group.resource_type);
|
||||
increment(statuses, group.status_class);
|
||||
}
|
||||
return {
|
||||
selected,
|
||||
transactions: selected === true || groups.length > 0 ? groups.length : null,
|
||||
without_request: withoutRequest,
|
||||
ambiguous_transactions: ambiguous,
|
||||
failed_transactions: failed,
|
||||
by_origin: sorted(origins).map(([origin, transactions]) => ({
|
||||
origin,
|
||||
transactions,
|
||||
})),
|
||||
by_resource_type: sorted(resources).map(
|
||||
([resource_type, transactions]) => ({ resource_type, transactions }),
|
||||
),
|
||||
by_status_class: sorted(statuses).map(([status_class, transactions]) => ({
|
||||
status_class,
|
||||
transactions,
|
||||
})),
|
||||
};
|
||||
};
|
||||
@@ -0,0 +1,388 @@
|
||||
import type { z } from "zod";
|
||||
import type { AnalysisError } from "../analysisErrorBase.js";
|
||||
import {
|
||||
retainedBrowserScenarioCaptureSchema,
|
||||
type RetainedBrowserScenarioCapture as BrowserScenarioCapture,
|
||||
} from "../browserScenarioCapture.js";
|
||||
import type { BrowserScenarioStep as Step } from "../browserScenarioCaptureValues.js";
|
||||
import { compareAsciiStrings } from "../canonicalOrdering.js";
|
||||
import { err, ok, type Result } from "../result.js";
|
||||
import { analysisViewInputError } from "./analysisViewErrors.js";
|
||||
import {
|
||||
completeWithinViewCoverage,
|
||||
pageViewCoverage,
|
||||
} from "./analysisViewCoverage.js";
|
||||
import { createAnalysisViewResultReader } from "./analysisViewParent.js";
|
||||
import type {
|
||||
AnalysisViewCoverage,
|
||||
AnalysisViewParent,
|
||||
AnalysisViewRequest,
|
||||
UnsignedAnalysisView,
|
||||
} from "./analysisView.js";
|
||||
import {
|
||||
ARTIFACT_SECTIONS,
|
||||
stepRowSchema,
|
||||
browserScenarioSummarySchema,
|
||||
stepSectionsSchema,
|
||||
summaryStepSchema,
|
||||
focusAccessibilitySchema,
|
||||
browserScenarioViewItemsSchema,
|
||||
type BrowserScenarioViewRequest,
|
||||
type ArtifactSection,
|
||||
} from "./browserScenarioViewSchemas.js";
|
||||
|
||||
import {
|
||||
browserScenarioTransactionGroups,
|
||||
summarizeBrowserScenarioNetwork,
|
||||
} from "./browserScenarioNetworkView.js";
|
||||
|
||||
const OPERATION = "capture_browser_scenario" as const;
|
||||
const readCapture = createAnalysisViewResultReader(
|
||||
retainedBrowserScenarioCaptureSchema,
|
||||
);
|
||||
|
||||
const unsupportedView = (): AnalysisError =>
|
||||
analysisViewInputError([
|
||||
{
|
||||
path: ["view"],
|
||||
reason: "invalid_value",
|
||||
message:
|
||||
'Parent Evidence operation "capture_browser_scenario" supports summary and browser-scenario views, plus compatible environment views.',
|
||||
},
|
||||
]);
|
||||
|
||||
const sameUrl = (
|
||||
left: Step["after_url"] | undefined,
|
||||
right: Step["before_url"],
|
||||
): boolean =>
|
||||
left !== undefined &&
|
||||
left.url === right.url &&
|
||||
left.redacted === right.redacted;
|
||||
|
||||
const stepSections = (step: Step): z.infer<typeof stepSectionsSchema> => {
|
||||
const sections: z.infer<typeof stepSectionsSchema> = {
|
||||
captured: [],
|
||||
missing: [],
|
||||
truncated: [],
|
||||
};
|
||||
for (const section of ARTIFACT_SECTIONS) {
|
||||
const { state } = step.artifacts[section];
|
||||
if (state !== "not_requested") sections[state].push(section);
|
||||
}
|
||||
return sections;
|
||||
};
|
||||
|
||||
const summaryStep = (
|
||||
step: Step,
|
||||
previous: Step | undefined,
|
||||
): z.infer<typeof summaryStepSchema> => ({
|
||||
step_index: step.step_index,
|
||||
step_id: step.step_id,
|
||||
action: step.action,
|
||||
status: step.status,
|
||||
error: step.error,
|
||||
elapsed_ms: step.elapsed_ms,
|
||||
...(sameUrl(previous?.after_url, step.before_url)
|
||||
? {}
|
||||
: { before_url: step.before_url }),
|
||||
after_url: step.after_url,
|
||||
events: {
|
||||
sequence_start: step.event_sequence_start,
|
||||
sequence_end: step.event_sequence_end,
|
||||
},
|
||||
sections: stepSections(step),
|
||||
completeness: step.completeness.status,
|
||||
});
|
||||
|
||||
/** The first unsuccessful step explains a failure; otherwise the final screen does. */
|
||||
const focusAccessibility = (
|
||||
steps: readonly Step[],
|
||||
): z.infer<typeof focusAccessibilitySchema> => {
|
||||
const unsuccessful = steps.findIndex(({ status }) => status !== "completed");
|
||||
const focusIndex = unsuccessful === -1 ? steps.length - 1 : unsuccessful;
|
||||
const focus = steps[focusIndex];
|
||||
if (focus === undefined) throw new Error("Capture has no steps");
|
||||
const kind =
|
||||
unsuccessful === -1 ? ("last-step" as const) : "first-unsuccessful-step";
|
||||
for (let index = focusIndex; index >= 0; index -= 1) {
|
||||
const accessibility = steps[index]?.artifacts.accessibility;
|
||||
if (accessibility?.state === "captured")
|
||||
return {
|
||||
focus_step_index: focusIndex,
|
||||
focus: kind,
|
||||
step_index: index,
|
||||
accessibility,
|
||||
};
|
||||
}
|
||||
return {
|
||||
focus_step_index: focusIndex,
|
||||
focus: kind,
|
||||
step_index: null,
|
||||
accessibility: focus.artifacts.accessibility,
|
||||
};
|
||||
};
|
||||
|
||||
/** Counts in canonical key order; a null origin sorts first. */
|
||||
const sortedCounts = <Key extends string | null>(
|
||||
counts: ReadonlyMap<Key, number>,
|
||||
): [Key, number][] =>
|
||||
[...counts].sort(([left], [right]) =>
|
||||
left === right
|
||||
? 0
|
||||
: left === null
|
||||
? -1
|
||||
: right === null
|
||||
? 1
|
||||
: compareAsciiStrings(left, right),
|
||||
);
|
||||
|
||||
const increment = <Key>(counts: Map<Key, number>, key: Key): void => {
|
||||
counts.set(key, (counts.get(key) ?? 0) + 1);
|
||||
};
|
||||
|
||||
const eventCounts = (
|
||||
capture: BrowserScenarioCapture,
|
||||
): z.infer<typeof browserScenarioSummarySchema>["events"] => {
|
||||
const kinds = new Map<
|
||||
BrowserScenarioCapture["events"]["items"][number]["kind"],
|
||||
number
|
||||
>();
|
||||
for (const event of capture.events.items) increment(kinds, event.kind);
|
||||
const { omissions } = capture.events;
|
||||
return {
|
||||
retained: capture.events.retained,
|
||||
dropped: capture.events.dropped,
|
||||
by_kind: sortedCounts(kinds).map(([kind, count]) => ({ kind, count })),
|
||||
omissions: {
|
||||
by_kind: omissions.by_kind,
|
||||
network_transactions: omissions.network_transactions.length,
|
||||
network_transaction_range: omissions.network_transaction_range,
|
||||
},
|
||||
};
|
||||
};
|
||||
|
||||
const selected = <Value>(
|
||||
filter: readonly Value[] | undefined,
|
||||
): ((value: Value) => boolean) => {
|
||||
if (filter === undefined) return () => true;
|
||||
const values = new Set(filter);
|
||||
return (value) => values.has(value);
|
||||
};
|
||||
|
||||
const stepRow = (
|
||||
{ artifacts: recorded, ...step }: Step,
|
||||
selection: ReadonlySet<ArtifactSection>,
|
||||
): z.infer<typeof stepRowSchema> => {
|
||||
const artifacts: z.infer<typeof stepRowSchema>["artifacts"] = {};
|
||||
const omitted: z.infer<typeof stepRowSchema>["omitted_artifacts"] = [];
|
||||
for (const section of ARTIFACT_SECTIONS) {
|
||||
const artifact = recorded[section];
|
||||
if (selection.has(section))
|
||||
Object.assign(artifacts, { [section]: artifact });
|
||||
else if (artifact.state !== "not_requested")
|
||||
omitted.push({ section, state: artifact.state });
|
||||
}
|
||||
return { ...step, artifacts, omitted_artifacts: omitted };
|
||||
};
|
||||
|
||||
/** Scan matching rows once and materialize only the requested page. */
|
||||
const selectedPage = <Input, Row>(
|
||||
source: readonly Input[],
|
||||
view: { readonly offset: number; readonly limit: number },
|
||||
matches: (item: Input, index: number) => boolean,
|
||||
project: (item: Input, index: number) => Row,
|
||||
): { rows: Row[]; coverage: AnalysisViewCoverage } => {
|
||||
const rows: Row[] = [];
|
||||
let total = 0;
|
||||
for (const [index, item] of source.entries()) {
|
||||
if (!matches(item, index)) continue;
|
||||
if (total >= view.offset && rows.length < view.limit)
|
||||
rows.push(project(item, index));
|
||||
total += 1;
|
||||
}
|
||||
return { rows, coverage: pageViewCoverage(view.offset, rows.length, total) };
|
||||
};
|
||||
|
||||
/** Text offsets are UTF-16 positions in the exact digest-bound retained artifact. */
|
||||
const textPage = (
|
||||
capture: BrowserScenarioCapture,
|
||||
view: Extract<BrowserScenarioViewRequest, { collection: "text" }>,
|
||||
) => {
|
||||
const artifact = capture.steps[view.step_index]!.artifacts[view.artifact];
|
||||
const value = artifact.state === "captured" ? artifact.value : null;
|
||||
const text = value?.text.slice(view.offset, view.offset + view.limit) ?? null;
|
||||
return {
|
||||
items: {
|
||||
collection: "text" as const,
|
||||
step_index: view.step_index,
|
||||
artifact: view.artifact,
|
||||
state: artifact.state,
|
||||
reason: "reason" in artifact ? artifact.reason : null,
|
||||
sha256: value?.sha256 ?? null,
|
||||
bytes: value?.bytes ?? null,
|
||||
observed: artifact.state === "truncated" ? artifact.observed : null,
|
||||
retained: artifact.state === "truncated" ? artifact.retained : null,
|
||||
text,
|
||||
},
|
||||
coverage: pageViewCoverage(
|
||||
view.offset,
|
||||
text?.length ?? 0,
|
||||
value?.text.length ?? 0,
|
||||
),
|
||||
};
|
||||
};
|
||||
|
||||
/** One stable page of exact recorded facts; no whole-result filtering arrays. */
|
||||
const pageRecords = (
|
||||
capture: BrowserScenarioCapture,
|
||||
view: BrowserScenarioViewRequest,
|
||||
): {
|
||||
readonly items: z.infer<typeof browserScenarioViewItemsSchema>;
|
||||
readonly coverage: AnalysisViewCoverage;
|
||||
} => {
|
||||
if (view.collection === "text") return textPage(capture, view);
|
||||
const stepSelected = selected(view.step_indices);
|
||||
if (view.collection === "steps") {
|
||||
const artifacts = new Set(view.artifacts);
|
||||
const page = selectedPage(
|
||||
capture.steps,
|
||||
view,
|
||||
({ step_index }) => stepSelected(step_index),
|
||||
(step) => stepRow(step, artifacts),
|
||||
);
|
||||
return {
|
||||
items: { collection: "steps", rows: page.rows },
|
||||
coverage: page.coverage,
|
||||
};
|
||||
}
|
||||
const kindSelected = selected(view.event_kinds);
|
||||
const transactionSelected = selected(view.transaction_ids);
|
||||
if (view.collection === "transactions") {
|
||||
const page = selectedPage(
|
||||
browserScenarioTransactionGroups(capture),
|
||||
view,
|
||||
(group) =>
|
||||
transactionSelected(group.transaction_id) &&
|
||||
(view.step_indices === undefined ||
|
||||
group.source_item_indices.some((index) =>
|
||||
stepSelected(capture.events.items[index]!.step_index),
|
||||
)),
|
||||
(group) => {
|
||||
const events: {
|
||||
item_index: number;
|
||||
event: BrowserScenarioCapture["events"]["items"][number];
|
||||
}[] = [];
|
||||
const omitted: {
|
||||
item_index: number;
|
||||
kind: BrowserScenarioCapture["events"]["items"][number]["kind"];
|
||||
}[] = [];
|
||||
for (const item_index of group.source_item_indices) {
|
||||
const event = capture.events.items[item_index]!;
|
||||
if (kindSelected(event.kind)) events.push({ item_index, event });
|
||||
else omitted.push({ item_index, kind: event.kind });
|
||||
}
|
||||
return {
|
||||
transaction_id: group.transaction_id,
|
||||
source_item_indices: [...group.source_item_indices],
|
||||
events,
|
||||
omitted_events: omitted,
|
||||
};
|
||||
},
|
||||
);
|
||||
return {
|
||||
items: { collection: "transactions", rows: page.rows },
|
||||
coverage: page.coverage,
|
||||
};
|
||||
}
|
||||
const page = selectedPage(
|
||||
capture.events.items,
|
||||
view,
|
||||
(event) =>
|
||||
stepSelected(event.step_index) &&
|
||||
kindSelected(event.kind) &&
|
||||
(view.transaction_ids === undefined ||
|
||||
("transaction_id" in event &&
|
||||
transactionSelected(event.transaction_id))),
|
||||
(event, item_index) => ({ item_index, event }),
|
||||
);
|
||||
return {
|
||||
items: { collection: "events", rows: page.rows },
|
||||
coverage: page.coverage,
|
||||
};
|
||||
};
|
||||
|
||||
/** Project retained scenario Evidence without relaunching the browser or replaying actions. */
|
||||
export const projectBrowserScenarioView = (
|
||||
parent: AnalysisViewParent,
|
||||
view: AnalysisViewRequest,
|
||||
): Result<UnsignedAnalysisView, AnalysisError> => {
|
||||
if (view.kind !== "summary" && view.kind !== "browser-scenario")
|
||||
return err(unsupportedView());
|
||||
const parsed = readCapture(parent);
|
||||
if (!parsed.ok) return parsed;
|
||||
const capture = parsed.value;
|
||||
const shared = {
|
||||
parent_evidence_id: parent.evidenceId,
|
||||
parent_operation: OPERATION,
|
||||
parent_digest: parent.evidenceId.slice(3),
|
||||
artifact: null,
|
||||
limitations: [...parent.limitations],
|
||||
unknowns: [
|
||||
"Step states record one controlled replay; they do not establish the application's current state.",
|
||||
"Event step references record receipt attribution; they do not prove an action caused a transaction.",
|
||||
...(capture.events.dropped > 0
|
||||
? [
|
||||
`${String(capture.events.dropped)} events were dropped by capture budgets; counts and pages cover retained events only.`,
|
||||
]
|
||||
: []),
|
||||
],
|
||||
};
|
||||
if (view.kind === "summary")
|
||||
return ok({
|
||||
kind: "summary",
|
||||
view,
|
||||
...shared,
|
||||
summary: {
|
||||
browser: capture.browser,
|
||||
scenario: capture.scenario,
|
||||
duration_ms: capture.duration_ms,
|
||||
completeness: capture.completeness,
|
||||
steps: capture.steps.map((step, index) =>
|
||||
summaryStep(step, capture.steps[index - 1]),
|
||||
),
|
||||
final_accessibility: focusAccessibility(capture.steps),
|
||||
events: eventCounts(capture),
|
||||
network: summarizeBrowserScenarioNetwork(capture),
|
||||
limitation_count: shared.limitations.length,
|
||||
},
|
||||
coverage: completeWithinViewCoverage(1, 1),
|
||||
});
|
||||
if (
|
||||
view.collection === "text" &&
|
||||
capture.steps[view.step_index] === undefined
|
||||
)
|
||||
return err(
|
||||
analysisViewInputError([
|
||||
{
|
||||
path: ["view", "step_index"],
|
||||
reason: "invalid_value",
|
||||
message: "The selected step is not present in the retained capture.",
|
||||
},
|
||||
]),
|
||||
);
|
||||
return ok({
|
||||
kind: "browser-scenario",
|
||||
view,
|
||||
...shared,
|
||||
source_completeness: capture.completeness,
|
||||
source_events: {
|
||||
retained: capture.events.retained,
|
||||
dropped: capture.events.dropped,
|
||||
},
|
||||
source_network_omissions: {
|
||||
transactions: capture.events.omissions.network_transactions.length,
|
||||
transaction_range: capture.events.omissions.network_transaction_range,
|
||||
},
|
||||
...pageRecords(capture, view),
|
||||
});
|
||||
};
|
||||
@@ -0,0 +1,250 @@
|
||||
import { z } from "zod";
|
||||
import { digestSchema } from "../digests.js";
|
||||
import { browserScenarioNetworkSummarySchema } from "./browserScenarioNetworkView.js";
|
||||
import { sanitizedBrowserUrlSchema } from "../browserObservation.js";
|
||||
import { retainedBrowserScenarioCaptureSchema } from "../browserScenarioCapture.js";
|
||||
import {
|
||||
browserScenarioCompletenessSchema,
|
||||
browserScenarioEventKindSchema,
|
||||
browserScenarioEventSchema,
|
||||
browserStepArtifactsSchema,
|
||||
} from "../browserScenarioCaptureValues.js";
|
||||
|
||||
export const ARTIFACT_SECTIONS = browserStepArtifactsSchema.keyof().options;
|
||||
const artifactSectionSchema = browserStepArtifactsSchema.keyof();
|
||||
export type ArtifactSection = z.infer<typeof artifactSectionSchema>;
|
||||
|
||||
const countSchema = z.number().int().nonnegative();
|
||||
/** Section names by recorded state; not_requested sections are omitted. */
|
||||
export const stepSectionsSchema = z.strictObject({
|
||||
captured: z.array(artifactSectionSchema),
|
||||
missing: z.array(artifactSectionSchema),
|
||||
truncated: z.array(artifactSectionSchema),
|
||||
});
|
||||
|
||||
export const summaryStepSchema = z.strictObject({
|
||||
step_index: countSchema,
|
||||
step_id: z.string().min(1),
|
||||
action: z.string().min(1),
|
||||
status: z.enum(["completed", "failed", "cancelled"]),
|
||||
error: z.string().nullable(),
|
||||
elapsed_ms: countSchema,
|
||||
before_url: sanitizedBrowserUrlSchema
|
||||
.exactOptional()
|
||||
.describe(
|
||||
"Present only when it differs from the previous step's after_url (always for step 0).",
|
||||
),
|
||||
after_url: sanitizedBrowserUrlSchema,
|
||||
events: z.strictObject({
|
||||
sequence_start: z.number().int().min(1),
|
||||
sequence_end: countSchema,
|
||||
}),
|
||||
sections: stepSectionsSchema,
|
||||
completeness: z.enum(["complete", "incomplete", "truncated"]),
|
||||
});
|
||||
|
||||
export const focusAccessibilitySchema = z.strictObject({
|
||||
focus_step_index: countSchema,
|
||||
focus: z.enum(["first-unsuccessful-step", "last-step"]),
|
||||
/** The step whose tree is returned: the focus step, or the nearest earlier step that captured one. */
|
||||
step_index: countSchema.nullable(),
|
||||
accessibility: browserStepArtifactsSchema.shape.accessibility,
|
||||
});
|
||||
|
||||
/** Compact capture overview; complete records stay in the retained parent. */
|
||||
export const browserScenarioSummarySchema = z.strictObject({
|
||||
browser: retainedBrowserScenarioCaptureSchema.shape.browser,
|
||||
scenario: retainedBrowserScenarioCaptureSchema.shape.scenario,
|
||||
duration_ms: countSchema,
|
||||
completeness: browserScenarioCompletenessSchema,
|
||||
steps: z.array(summaryStepSchema),
|
||||
final_accessibility: focusAccessibilitySchema,
|
||||
events: z.strictObject({
|
||||
retained: countSchema,
|
||||
dropped: countSchema,
|
||||
by_kind: z.array(
|
||||
z.strictObject({
|
||||
kind: browserScenarioEventKindSchema,
|
||||
count: countSchema,
|
||||
}),
|
||||
),
|
||||
omissions: z.strictObject({
|
||||
by_kind:
|
||||
retainedBrowserScenarioCaptureSchema.shape.events.shape.omissions.shape
|
||||
.by_kind,
|
||||
network_transactions: countSchema,
|
||||
network_transaction_range:
|
||||
retainedBrowserScenarioCaptureSchema.shape.events.shape.omissions.shape
|
||||
.network_transaction_range,
|
||||
}),
|
||||
}),
|
||||
network: browserScenarioNetworkSummarySchema,
|
||||
limitation_count: countSchema.describe(
|
||||
"Number of parent Evidence limitations returned with this summary, including inherited provenance caveats.",
|
||||
),
|
||||
});
|
||||
|
||||
const pageShape = {
|
||||
kind: z.literal("browser-scenario"),
|
||||
offset: countSchema.default(0),
|
||||
limit: z.int().positive().default(64),
|
||||
};
|
||||
const stepSelection = {
|
||||
step_indices: z
|
||||
.array(countSchema)
|
||||
.optional()
|
||||
.describe(
|
||||
"Exact recorded step indices; omitted selects all, [] selects none.",
|
||||
),
|
||||
};
|
||||
const transactionSelection = {
|
||||
transaction_ids: z
|
||||
.array(z.string().min(1))
|
||||
.optional()
|
||||
.describe(
|
||||
"Exact recorded transaction IDs; omitted selects all, [] selects none.",
|
||||
),
|
||||
};
|
||||
|
||||
/** Collection-specific fields are validated rather than silently ignored. */
|
||||
export const browserScenarioViewRequestSchema = z.discriminatedUnion(
|
||||
"collection",
|
||||
[
|
||||
z.strictObject({
|
||||
...pageShape,
|
||||
...stepSelection,
|
||||
collection: z.literal("steps"),
|
||||
artifacts: z
|
||||
.array(artifactSectionSchema)
|
||||
.default([])
|
||||
.describe(
|
||||
"Return only selected artifact payloads; omitted_artifacts names the other recorded sections.",
|
||||
),
|
||||
}),
|
||||
z.strictObject({
|
||||
...pageShape,
|
||||
...stepSelection,
|
||||
...transactionSelection,
|
||||
collection: z.literal("events"),
|
||||
event_kinds: z
|
||||
.array(browserScenarioEventKindSchema)
|
||||
.optional()
|
||||
.describe("Omitted selects all event kinds; [] selects none."),
|
||||
}),
|
||||
z.strictObject({
|
||||
...pageShape,
|
||||
...stepSelection,
|
||||
...transactionSelection,
|
||||
collection: z.literal("transactions"),
|
||||
event_kinds: z
|
||||
.array(browserScenarioEventKindSchema)
|
||||
.default([
|
||||
"request",
|
||||
"response",
|
||||
"request-finished",
|
||||
"request-failed",
|
||||
"request-unfinished",
|
||||
])
|
||||
.describe(
|
||||
"Metadata events by default; select network-content explicitly for bodies and header values. [] returns identity and source indices only.",
|
||||
),
|
||||
}),
|
||||
z.strictObject({
|
||||
...pageShape,
|
||||
collection: z.literal("text"),
|
||||
step_index: countSchema,
|
||||
artifact: z.enum(["accessibility", "dom"]),
|
||||
limit: z
|
||||
.int()
|
||||
.positive()
|
||||
.default(2048)
|
||||
.describe("Caller-selected UTF-16 code units, matching offset."),
|
||||
}),
|
||||
],
|
||||
);
|
||||
export type BrowserScenarioViewRequest = z.output<
|
||||
typeof browserScenarioViewRequestSchema
|
||||
>;
|
||||
|
||||
/** One exact step whose unselected captured sections are named rather than returned. */
|
||||
export const stepRowSchema = z.strictObject({
|
||||
step_index: countSchema,
|
||||
step_id: z.string().min(1),
|
||||
action: z.string().min(1),
|
||||
status: z.enum(["completed", "failed", "cancelled"]),
|
||||
error: z.string().nullable(),
|
||||
elapsed_ms: countSchema,
|
||||
before_url: sanitizedBrowserUrlSchema,
|
||||
after_url: sanitizedBrowserUrlSchema,
|
||||
event_sequence_start: z.number().int().min(1),
|
||||
event_sequence_end: countSchema,
|
||||
completeness: browserScenarioCompletenessSchema,
|
||||
artifacts: browserStepArtifactsSchema.partial(),
|
||||
omitted_artifacts: z.array(
|
||||
z.strictObject({
|
||||
section: artifactSectionSchema,
|
||||
state: z.enum(["captured", "missing", "truncated"]),
|
||||
}),
|
||||
),
|
||||
});
|
||||
const eventRowSchema = z.strictObject({
|
||||
item_index: countSchema,
|
||||
event: browserScenarioEventSchema,
|
||||
});
|
||||
|
||||
export const browserScenarioViewItemsSchema = z.discriminatedUnion(
|
||||
"collection",
|
||||
[
|
||||
z.strictObject({
|
||||
collection: z.literal("steps"),
|
||||
rows: z.array(stepRowSchema),
|
||||
}),
|
||||
z.strictObject({
|
||||
collection: z.literal("events"),
|
||||
rows: z.array(eventRowSchema),
|
||||
}),
|
||||
z.strictObject({
|
||||
collection: z.literal("transactions"),
|
||||
rows: z.array(
|
||||
z.strictObject({
|
||||
transaction_id: z.string().min(1),
|
||||
source_item_indices: z.array(countSchema),
|
||||
events: z.array(eventRowSchema),
|
||||
omitted_events: z.array(
|
||||
z.strictObject({
|
||||
item_index: countSchema,
|
||||
kind: browserScenarioEventKindSchema,
|
||||
}),
|
||||
),
|
||||
}),
|
||||
),
|
||||
}),
|
||||
z.strictObject({
|
||||
collection: z.literal("text"),
|
||||
step_index: countSchema,
|
||||
artifact: z.enum(["accessibility", "dom"]),
|
||||
state: z.enum(["captured", "missing", "truncated", "not_requested"]),
|
||||
reason: z.string().nullable(),
|
||||
sha256: digestSchema.nullable(),
|
||||
bytes: countSchema.nullable(),
|
||||
observed: countSchema.nullable(),
|
||||
retained: countSchema.nullable(),
|
||||
text: z.string().nullable(),
|
||||
}),
|
||||
],
|
||||
);
|
||||
|
||||
/** Capture-wide facts every page repeats so exhaustion is not read as completeness. */
|
||||
export const browserScenarioViewContextSchema = z.strictObject({
|
||||
source_completeness: browserScenarioCompletenessSchema,
|
||||
source_events: z.strictObject({
|
||||
retained: countSchema,
|
||||
dropped: countSchema,
|
||||
}),
|
||||
source_network_omissions: z.strictObject({
|
||||
transactions: countSchema,
|
||||
transaction_range:
|
||||
retainedBrowserScenarioCaptureSchema.shape.events.shape.omissions.shape
|
||||
.network_transaction_range,
|
||||
}),
|
||||
});
|
||||
@@ -1290,6 +1290,7 @@ const registerObservationTools = ({
|
||||
});
|
||||
registerBrowserScenarioTool(server, {
|
||||
...common,
|
||||
evidenceById,
|
||||
provider: options.browserScenarioCapture,
|
||||
loadFailure: options.optionalProviderLoadFailures?.browserScenarioCapture,
|
||||
});
|
||||
|
||||
@@ -1,82 +1,67 @@
|
||||
import type { EvidenceMcpServer } from "./EvidenceMcpServer.js";
|
||||
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
|
||||
import type { EvidenceLookup } from "../application/EvidenceInputResolver.js";
|
||||
import {
|
||||
optionalProviderUnavailable,
|
||||
type OptionalProviderLoadFailure,
|
||||
} from "../application/OptionalObservationProviders.js";
|
||||
import { err } from "../domain/result.js";
|
||||
|
||||
import { browserScenarioSchema } from "../domain/browserScenario.js";
|
||||
import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
|
||||
import type { BrowserScenarioCapturePort } from "../application/BrowserScenarioCapturePort.js";
|
||||
import { captureBrowserScenario } from "../application/BrowserScenarioCaptureService.js";
|
||||
import { toolContract } from "../contracts/toolContracts.js";
|
||||
import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
|
||||
import { browserScenarioSchema } from "../domain/browserScenario.js";
|
||||
import type { Logger } from "pino";
|
||||
import { logToolExecution } from "./toolLogging.js";
|
||||
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
|
||||
import type { WithAdmittedAnalysis } from "./analysisAdmission.js";
|
||||
import { runAdmittedToolOperation } from "./admittedToolOperation.js";
|
||||
import { deliverEvidenceResult } from "./contractToolHandler.js";
|
||||
import { createRetainedSummaryToolHandler } from "./contractToolHandler.js";
|
||||
|
||||
interface BrowserScenarioToolRegistration {
|
||||
readonly logger: Logger;
|
||||
readonly loadFailure?: OptionalProviderLoadFailure | undefined;
|
||||
readonly provider: BrowserScenarioCapturePort | undefined;
|
||||
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
|
||||
readonly evidenceById?: EvidenceLookup | undefined;
|
||||
readonly withAdmittedAnalysis?: WithAdmittedAnalysis;
|
||||
}
|
||||
|
||||
/** Register the browser scenario tool with execution-time provider diagnostics. */
|
||||
/** Validate one scenario, then share complete/retained delivery with other analyses. */
|
||||
export const registerBrowserScenarioTool = (
|
||||
server: EvidenceMcpServer,
|
||||
options: BrowserScenarioToolRegistration,
|
||||
): void => {
|
||||
const contract = toolContract("capture_browser_scenario");
|
||||
const handler = createRetainedSummaryToolHandler(
|
||||
server,
|
||||
contract,
|
||||
async (input, execution) => {
|
||||
// The SDK admits the advertised structure. The canonical semantic parser
|
||||
// owns field-path diagnostics, shared with the CLI rather than flattened
|
||||
// into the SDK's pre-handler validation message.
|
||||
const scenario = browserScenarioSchema.safeParse(input);
|
||||
if (!scenario.success)
|
||||
return err(
|
||||
analysisInputErrorFromIssues(
|
||||
contract.name,
|
||||
scenario.error.issues,
|
||||
input,
|
||||
{ cause: scenario.error },
|
||||
),
|
||||
);
|
||||
return options.loadFailure === undefined
|
||||
? captureBrowserScenario(options.provider, scenario.data, execution)
|
||||
: err(optionalProviderUnavailable(options.loadFailure, contract.name));
|
||||
},
|
||||
options.logger,
|
||||
{
|
||||
recordEvidence: options.recordEvidence,
|
||||
evidenceById: options.evidenceById,
|
||||
},
|
||||
options.withAdmittedAnalysis,
|
||||
);
|
||||
server.registerTool(
|
||||
contract.name,
|
||||
toolRegistrationOptions(contract),
|
||||
async (input, context) => {
|
||||
const parsedScenario = browserScenarioSchema.safeParse(input);
|
||||
if (!parsedScenario.success)
|
||||
return server.delivery.toCallToolResult(
|
||||
err(
|
||||
analysisInputErrorFromIssues(
|
||||
contract.name,
|
||||
parsedScenario.error.issues,
|
||||
input,
|
||||
{ cause: parsedScenario.error },
|
||||
),
|
||||
),
|
||||
contract,
|
||||
);
|
||||
const scenario = parsedScenario.data;
|
||||
if (options.loadFailure !== undefined)
|
||||
return server.delivery.toCallToolResult(
|
||||
err(optionalProviderUnavailable(options.loadFailure, contract.name)),
|
||||
contract,
|
||||
);
|
||||
return runAdmittedToolOperation(
|
||||
server,
|
||||
options.withAdmittedAnalysis,
|
||||
contract.name,
|
||||
context.mcpReq.signal,
|
||||
async () => {
|
||||
const result = await logToolExecution(
|
||||
options.logger,
|
||||
contract.name,
|
||||
() =>
|
||||
captureBrowserScenario(options.provider, scenario, {
|
||||
signal: context.mcpReq.signal,
|
||||
}),
|
||||
);
|
||||
return deliverEvidenceResult(
|
||||
server,
|
||||
result,
|
||||
contract,
|
||||
options.recordEvidence,
|
||||
);
|
||||
},
|
||||
);
|
||||
},
|
||||
handler,
|
||||
);
|
||||
};
|
||||
Reference in new issue
Block a user