Files
reverse-engineering-anything/src/application/environment/environmentReplay.ts
T
Edgar ArakelyanandClaude Opus 5.5 9196cf7302 fix(environment): mark every replay result, warn about the captured catalog and bound base64 decoding
- A transport wrapper marks every tools/call result as target content,
  including the argument errors the SDK returns before a replay runs.
- The server's instructions add that tool names, descriptions, parameter
  names and observed values come from the capture too, so the catalog is
  treated as data like the replies.
- Strict UTF-8 decoding keeps a leading byte-order mark instead of
  dropping it from the recorded text.
- A large retained base64 body is decoded only as far as the 256 KiB a
  reply can carry, and the replay reports it truncated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-18 20:58:38 -07:00

183 lines
6.3 KiB
TypeScript

import { isJsonLike } from "../../domain/analysisView/EnvironmentManifestAccumulator.js";
import { mediaTypeEssence } from "../../domain/analysisView/webNetworkRouteTemplates.js";
import type { AnalysisError } from "../../domain/analysisErrorBase.js";
import { AnalysisInputError } from "../../domain/analysisErrorCore.js";
import { jsonValueSchema, type JsonValue } from "../../domain/jsonValue.js";
import { err, ok, type Result } from "../../domain/result.js";
import { safeParseJson } from "../../domain/safeJson.js";
import { environmentToolArguments } from "./environmentTools.js";
import {
REPLAY_BODY_LIMIT_BYTES,
ENVIRONMENT_SERVE_OPERATION,
type EnvironmentManifestTool,
type EnvironmentSource,
type RecordedExchange,
} from "./environmentSource.js";
export { REPLAY_BODY_LIMIT_BYTES } from "./environmentSource.js";
/** Caller arguments as the MCP tool receives them. */
export type ReplayArguments = Readonly<Record<string, unknown>>;
/** What one tool call returns: the recorded response and where it came from. */
export interface ReplayResult {
readonly status: number | null;
readonly content_type: string | null;
readonly body: JsonValue;
readonly replay: {
readonly record_ordinal: number;
readonly evidence_id: string;
readonly exact_match: boolean;
readonly recorded_path: string;
readonly recorded_query: string | null;
readonly body_recorded: boolean;
readonly body_encoding: "utf-8" | "base64";
readonly truncated: boolean;
};
}
interface MatchScore {
readonly pathMatches: number;
readonly queryMatches: number;
readonly exact: boolean;
}
const decoded = (segment: string): string => {
try {
return decodeURIComponent(segment);
} catch {
return segment;
}
};
/** Count how many supplied path and query values the recorded request line satisfies. */
const scoreExchange = (
tool: EnvironmentManifestTool,
queryArguments: ReadonlyMap<string, string>,
exchange: RecordedExchange,
args: ReplayArguments,
): MatchScore => {
const segments = exchange.path.split("/").slice(1);
let pathProvided = 0;
let pathMatches = 0;
for (const param of tool.params) {
const value = args[param.name];
if (typeof value !== "string") continue;
pathProvided += 1;
const segment = segments[param.index];
if (
segment !== undefined &&
(segment === value || decoded(segment) === value)
)
pathMatches += 1;
}
const query = new URLSearchParams(exchange.query ?? "");
let queryProvided = 0;
let queryMatches = 0;
for (const [name, argument] of queryArguments) {
const value = args[argument];
if (typeof value !== "string") continue;
queryProvided += 1;
if (query.getAll(name).includes(value)) queryMatches += 1;
}
return {
pathMatches,
queryMatches,
exact: pathMatches === pathProvided && queryMatches === queryProvided,
};
};
/** Choose the record whose path segments, then query values, best match the call; ties keep manifest order. */
export const selectReplayExchange = (
tool: EnvironmentManifestTool,
exchanges: ReadonlyMap<number, RecordedExchange>,
args: ReplayArguments,
):
| { readonly exchange: RecordedExchange; readonly exact: boolean }
| undefined => {
let best: { exchange: RecordedExchange; score: MatchScore } | undefined;
const queryArguments = environmentToolArguments(tool).query;
for (const ordinal of tool.record_ordinals) {
const exchange = exchanges.get(ordinal);
if (exchange === undefined) continue;
const score = scoreExchange(tool, queryArguments, exchange, args);
if (
best === undefined ||
score.pathMatches > best.score.pathMatches ||
(score.pathMatches === best.score.pathMatches &&
score.queryMatches > best.score.queryMatches)
)
best = { exchange, score };
}
return best === undefined
? undefined
: { exchange: best.exchange, exact: best.score.exact };
};
/** The longest prefix of text whose UTF-8 encoding fits the byte limit, encoding only that prefix. */
const utf8Prefix = (text: string, maxBytes: number): string => {
// encodeInto stops before the first character that does not fit, so `read` ends on a boundary.
const { read } = new TextEncoder().encodeInto(text, new Uint8Array(maxBytes));
return text.slice(0, read);
};
/** Parse a retained body as JSON when its content type is JSON-like; otherwise return the text. */
const replayBody = (
exchange: RecordedExchange,
): { readonly body: JsonValue; readonly truncated: boolean } => {
const text = exchange.bodyText;
if (text === null) return { body: null, truncated: false };
const prefix = utf8Prefix(text, REPLAY_BODY_LIMIT_BYTES);
if (prefix.length < text.length || exchange.bodyCut === true)
return { body: prefix, truncated: true };
if (exchange.bodyEncoding === "base64")
return { body: text, truncated: false };
if (
exchange.contentType !== null &&
isJsonLike(mediaTypeEssence(exchange.contentType))
) {
const parsed = safeParseJson(text);
const value = parsed.ok
? jsonValueSchema.safeParse(parsed.value)
: undefined;
if (value?.success === true) return { body: value.data, truncated: false };
}
return { body: text, truncated: false };
};
/** Replay one tool call from the retained record that best matches its arguments. */
export const replayEnvironmentTool = (
source: EnvironmentSource,
tool: EnvironmentManifestTool,
args: ReplayArguments,
): Result<ReplayResult, AnalysisError> => {
const selected = selectReplayExchange(tool, source.exchanges, args);
if (selected === undefined)
return err(
new AnalysisInputError(
ENVIRONMENT_SERVE_OPERATION,
{
userMessage: `Tool ${tool.name} cites no retained record to replay.`,
},
[{ path: ["tool"], reason: "invalid_value", expected: tool.name }],
),
);
const { exchange, exact } = selected;
const { body, truncated } = replayBody(exchange);
return ok({
status: exchange.status,
content_type: exchange.contentType,
body,
replay: {
record_ordinal: exchange.ordinal,
evidence_id: source.evidenceId,
exact_match: exact,
recorded_path: exchange.path,
recorded_query: exchange.query,
body_recorded: exchange.bodyText !== null,
body_encoding: exchange.bodyEncoding ?? "utf-8",
truncated,
},
});
};