Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
import { describe, expect, it } from "vitest";
import {
timedCaptureEvidence,
type TimedCaptureRow,
} from "../../../tests/fixtures/analysisView.js";
import {
environmentStateServeFixture,
environmentStateServeInputs,
} from "../../../tests/fixtures/environmentServe.js";
import { projectAnalysisError } from "../../domain/analysisErrorProjection.js";
import {
REPLAY_BODY_LIMIT_BYTES,
type EnvironmentSource,
} from "./environmentSource.js";
import {
answerFromState,
type StateServing,
} from "./environmentStateAnswer.js";
import { EnvironmentStateStore } from "./environmentStateStore.js";
const grafana = environmentStateServeInputs();
const servingOf = (
inputs: typeof grafana = grafana,
): StateServing & { readonly store: EnvironmentStateStore } => ({
source: inputs.source,
store: new EnvironmentStateStore(inputs.state),
});
/** Serve the state the view extracts from a synthetic timed capture. */
const servingFrom = (rows: readonly TimedCaptureRow[]) =>
servingOf(
environmentStateServeInputs(
environmentStateServeFixture(timedCaptureEvidence(rows)),
),
);
const toolOf = (source: EnvironmentSource, name: string) => {
const found = source.manifest.tools.find((tool) => tool.name === name);
if (found === undefined) throw new Error(`Fixture manifest lacks ${name}`);
return found;
};
const answer = (
serving: StateServing,
name: string,
args: Readonly<Record<string, unknown>>,
) => {
const result = answerFromState(serving, toolOf(serving.source, name), args);
if (!result.ok) throw result.error;
return result.value;
};
const refusal = (
serving: StateServing,
name: string,
args: Readonly<Record<string, unknown>>,
) => {
const result = answerFromState(serving, toolOf(serving.source, name), args);
if (result.ok) throw new Error(`Expected ${name} to be refused`);
return projectAnalysisError(result.error);
};
/** A list with one proved whole line keeps an entity added to an empty later page off that page. */
const expectAddedEntityStaysOffPage = (
query: string,
args: Readonly<Record<string, unknown>>,
membership: "recorded" | "query" = "query",
): void => {
const alpha = { id: 1, name: "Alpha" };
const serving = servingFrom([
["GET", "/api/orgs/1/books", [alpha]],
["GET", "/api/orgs/1/books/1", alpha],
["GET", `/api/orgs/2/books?${query}`, []],
]);
expect(serving.store.state.views.get("get_orgs_books_by_id")).toMatchObject({
shape: "list",
membership: "recorded",
});
load(serving, (entities) => [
...entities,
{
type: "/api/orgs/{numeric}/books",
collection: "/api/orgs/2/books",
id: "9",
fields: { id: 9, name: "Added" },
},
]);
expect(
answer(serving, "get_orgs_books_by_id", { id: "2", ...args }),
).toMatchObject({
body: [],
state: { source: "state", membership, listed: 0 },
});
// Without a proved whole line here, the argument-less call keeps recorded members.
expect(answer(serving, "get_orgs_books_by_id", { id: "2" })).toMatchObject({
body: [],
state:
membership === "query"
? { source: "state", membership: "recorded", listed: 0 }
: { source: "recording", reason: "unrecorded-request" },
});
};
/** A list with one proved whole line keeps an entity added to an empty start page off that page. */
const expectAddedEntityStaysOffStartPage = (name: string): void =>
expectAddedEntityStaysOffPage(`${name}=1`, { [name]: "1" });
/** Replace the served state with the initial one changed by `edit`. */
const load = (
serving: ReturnType<typeof servingOf>,
edit: (entities: Record<string, unknown>[]) => Record<string, unknown>[],
documents: unknown[] = [],
): void => {
const initial = structuredClone(serving.store.snapshot().rea_state);
const replaced = serving.store.replace({
rea_state: {
version: 1,
entities: edit(initial.entities as unknown as Record<string, unknown>[]),
documents,
},
});
if (!replaced.ok) throw replaced.error;
};
describe("item answers", () => {
it("renders the named entity into the recorded envelope with the base record's provenance", () => {
const serving = servingOf();
const probe = answer(serving, "get_users_by_id", { id: "2" });
expect(probe).toMatchObject({
status: 200,
content_type: "application/json",
body: { id: 2, login: "probe", email: "[email protected]" },
replay: { record_ordinal: 5, exact_match: true, truncated: false },
state: {
source: "state",
view: "item",
type: "/api/users",
collection: "/api/users",
id: "2",
},
});
// The envelope comes from one record; another entity is still answered from the state.
expect(answer(serving, "get_users_by_id", { id: "3" })).toMatchObject({
body: { login: "viewer" },
replay: { record_ordinal: 5, exact_match: false },
});
expect(
answer(serving, "get_dashboards_by_uid", { uid: "acb4v6" }),
).toMatchObject({
body: {
meta: { type: "db", folderUid: "fg1jo91e57e2ob" },
dashboard: { uid: "acb4v6", title: "probe dashboard", panels: [] },
},
});
load(serving, (entities) =>
entities.map((entity) =>
entity.type === "/api/users" && entity.id === "3"
? {
...entity,
fields: { ...(entity.fields as object), login: "renamed" },
}
: entity,
),
);
expect(answer(serving, "get_users_by_id", { id: "3" })).toMatchObject({
body: { login: "renamed" },
});
});
it("refuses an entity the state does not hold or one missing a field the view requires", () => {
const serving = servingOf();
expect(refusal(serving, "get_users_by_id", { id: "999" })).toMatchObject({
code: "invalid_request",
message: expect.stringContaining("holds no /api/users entity 999"),
});
load(serving, (entities) =>
entities.map((entity) => {
if (entity.type !== "/api/users" || entity.id !== "2") return entity;
const { email: _email, ...fields } = entity.fields as Record<
string,
unknown
>;
return { ...entity, fields };
}),
);
expect(refusal(serving, "get_users_by_id", { id: "2" })).toMatchObject({
message: expect.stringContaining("lacks fields"),
});
expect(refusal(serving, "get_users_by_id", {})).toMatchObject({
message: expect.stringContaining("needs every path argument"),
});
});
it("matches path arguments as replay does, verbatim or percent-decoded, without re-splitting them", () => {
const files = servingFrom([
["GET", "/api/files/a%2Fb1", { id: "a/b1", name: "x" }],
["GET", "/api/files/c2", { id: "c2", name: "y" }],
["GET", "/api/files/d3", { id: "d3", name: "z" }],
]);
for (const file_id of ["a/b1", "a%2Fb1"])
expect(answer(files, "get_files_by_file_id", { file_id })).toMatchObject({
body: { id: "a/b1", name: "x" },
state: { source: "state", collection: "/api/files", id: "a/b1" },
});
const orgs = servingFrom([
["GET", "/api/orgs/my%20org1/users/1", { id: 1, name: "x" }],
["GET", "/api/orgs/org2/users/2", { id: 2, name: "y" }],
["GET", "/api/orgs/org3/users/3", { id: 3, name: "z" }],
]);
for (const org_id of ["my org1", "my%20org1"])
expect(
answer(orgs, "get_orgs_users_by_org_id_id", { org_id, id: "1" }),
).toMatchObject({
body: { id: 1, name: "x" },
replay: { exact_match: true },
state: { collection: "/api/orgs/my%20org1/users", id: "1" },
});
expect(
refusal(orgs, "get_orgs_users_by_org_id_id", { org_id: "org2", id: "1" }),
).toMatchObject({
message: expect.stringContaining(
"holds no /api/orgs/{org_id}/users entity 1 in /api/orgs/org2/users",
),
});
});
});
describe("loaded later pages", () => {
it.each(["offset", "start", "_start"])(
"skips an entity added under an empty ?%s=1 page without whole-collection evidence",
expectAddedEntityStaysOffStartPage,
);
it("does not list an entity added under an empty ?page=2&per_page=1 page", () => {
expectAddedEntityStaysOffPage(
"page=2&per_page=1",
{ page: "2", per_page: "1" },
"recorded",
);
});
});
describe("list answers", () => {
it("lists every entity of the collection in state order when membership is all", () => {
const serving = servingOf();
const args = { uid: "acb4v6" };
expect(
answer(serving, "get_dashboards_versions_by_uid", args),
).toMatchObject({
body: { versions: [{ id: 1, version: 1 }] },
replay: { record_ordinal: 11, exact_match: true },
state: {
source: "state",
view: "list",
collection: "/api/dashboards/uid/acb4v6/versions",
membership: "all",
listed: 1,
},
});
load(serving, (entities) => [
...entities,
{
type: "/api/dashboards/uid/{uid}/versions",
collection: "/api/dashboards/uid/acb4v6/versions",
id: "2",
fields: { id: 2, version: 2 },
},
]);
expect(
answer(serving, "get_dashboards_versions_by_uid", args).body,
).toEqual({
versions: [
{ id: 1, version: 1 },
{ id: 2, version: 2 },
],
});
});
it("lists the recorded members that remain when membership is recorded", () => {
const serving = servingOf();
const args = { limit: "100", page: "1" };
expect(answer(serving, "get_folders", args)).toMatchObject({
body: [{ id: 5, uid: "fg1jo91e57e2ob", title: "probe folder" }],
state: { view: "list", membership: "recorded", listed: 1 },
});
load(serving, (entities) =>
entities.filter((entity) => entity.id !== "fg1jo91e57e2ob"),
);
expect(answer(serving, "get_folders", args)).toMatchObject({
body: [],
state: { listed: 0 },
});
});
it("renders only the lines its view checked, never a later or filtered recording", () => {
const teams = servingFrom([
["GET", "/api/teams", [{ id: 1 }, { id: 2 }]],
["POST", "/api/teams", { id: 3 }],
["GET", "/api/teams?perpage=1", [{ id: 1 }]],
]);
expect(answer(teams, "get_teams", {})).toMatchObject({
body: [{ id: 1 }, { id: 2 }],
replay: { record_ordinal: 0 },
state: { source: "state", membership: "all", listed: 2 },
});
expect(answer(teams, "get_teams", { perpage: "1" })).toMatchObject({
body: [{ id: 1 }],
replay: { record_ordinal: 2 },
state: { source: "recording", reason: "unrecorded-request" },
});
// Replay's tie-break picks the first line here, but the arguments name the second exactly.
const items = servingFrom([
["GET", "/api/items?a=1&b=2", [{ id: 1 }]],
["GET", "/api/items?a=1", [{ id: 1 }, { id: 2 }]],
]);
expect(answer(items, "get_items", { a: "1" })).toMatchObject({
body: [{ id: 1 }, { id: 2 }],
replay: { record_ordinal: 1, recorded_query: "?a=1" },
state: { source: "state", membership: "recorded", listed: 2 },
});
expect(answer(items, "get_items", { a: "1", b: "2" })).toMatchObject({
body: [{ id: 1 }],
replay: { record_ordinal: 0 },
state: { source: "state", listed: 1 },
});
});
it("answers an unfiltered call from a paging-only line of the parent its path arguments name", () => {
const books = servingFrom([
["GET", "/api/orgs/1/books?limit=50", [{ id: 1 }, { id: 2 }]],
["GET", "/api/orgs/2/books?limit=50", [{ id: 3 }]],
["GET", "/api/orgs/3/books?limit=50", [{ id: 4 }]],
]);
expect(answer(books, "get_orgs_books_by_id", { id: "2" })).toMatchObject({
body: [{ id: 3 }],
replay: { record_ordinal: 1, exact_match: false },
state: {
source: "state",
collection: "/api/orgs/2/books",
membership: "all",
listed: 1,
},
});
expect(answer(books, "get_orgs_books_by_id", { id: "9" })).toMatchObject({
state: { source: "recording", reason: "unrecorded-request" },
});
});
it("answers a recorded call that pages by two parameters as it recorded, whatever order they are supplied in", () => {
const books = servingFrom([
["GET", "/api/books", [{ id: 1 }, { id: 2 }, { id: 3 }]],
["GET", "/api/books?size=2&limit=1", [{ id: 1 }]],
]);
expect(answer(books, "get_books", { size: "2", limit: "1" })).toMatchObject(
{
body: [{ id: 1 }],
replay: { record_ordinal: 1, exact_match: true },
state: { source: "state", membership: "query", listed: 1 },
},
);
});
it("refuses a list whose member lacks a field every recording carried, never answering a partial body", () => {
const serving = servingOf();
load(serving, (entities) =>
entities.map((entity) => {
if (entity.type !== "/api/folders" || entity.id !== "fg1jo91e57e2ob")
return entity;
const { title: _title, ...fields } = entity.fields as Record<
string,
unknown
>;
return { ...entity, fields };
}),
);
expect(
refusal(serving, "get_folders", { limit: "100", page: "1" }),
).toMatchObject({
code: "invalid_request",
message: expect.stringContaining(
"holds no complete /api/folders entity fg1jo91e57e2ob in /api/folders: it lacks fields this tool's responses always carried: title",
),
});
});
it("answers an unrecorded request line from its recording", () => {
const serving = servingOf();
load(serving, () => []);
for (const args of [{ limit: "50", page: "1" }, { limit: "100" }, {}])
expect(answer(serving, "get_folders", args)).toMatchObject({
body: [{ uid: "fg1jo91e57e2ob" }],
state: { source: "recording", reason: "unrecorded-request" },
});
});
});
describe("recorded and document answers", () => {
it("replays recorded views and tools without a view, saying why", () => {
const serving = servingOf();
expect(answer(serving, "get_annotations", {})).toMatchObject({
replay: { record_ordinal: 25 },
state: { source: "recording", reason: "no-init-recording" },
});
expect(answer(serving, "post_folders", {})).toMatchObject({
state: { source: "recording", reason: "no-view" },
});
});
it("replays a read whose rendered document exceeds the body limit", () => {
const values = Array.from({ length: 60_000 }, () => "1e3").join(",");
const body = `{"values":[${values}]}`;
const serving = servingFrom([["GET", "/api/config", body]]);
expect(serving.store.state.documents).toEqual([]);
expect(answer(serving, "get_config", {})).toMatchObject({
replay: { record_ordinal: 0 },
state: { source: "recording", reason: "rendered-oversize" },
});
});
it("answers a document's recorded line with the state's value for it", () => {
const capture = timedCaptureEvidence([
["GET", "/api/settings", { theme: "dark", density: "compact" }],
["PUT", "/api/settings", { theme: "light", density: "compact" }],
["GET", "/api/settings", { theme: "light", density: "compact" }],
]);
const serving = servingOf(
environmentStateServeInputs(environmentStateServeFixture(capture)),
);
expect(answer(serving, "get_settings", {})).toMatchObject({
body: { theme: "dark", density: "compact" },
replay: { record_ordinal: 0, exact_match: true },
state: { source: "state", view: "document", path: "/api/settings" },
});
load(serving, (entities) => entities, [
{ tool: "get_settings", path: "/api/settings", value: { theme: "blue" } },
]);
expect(answer(serving, "get_settings", {}).body).toEqual({ theme: "blue" });
// Only the Evidence's own value cites its record; an edited one cites none and an invented citation is refused.
expect(serving.store.snapshot().rea_state.documents).toEqual([
{ tool: "get_settings", path: "/api/settings", value: { theme: "blue" } },
]);
load(serving, (entities) => entities, [
{
tool: "get_settings",
path: "/api/settings",
value: { theme: "dark", density: "compact" },
},
]);
expect(serving.store.snapshot().rea_state.documents).toEqual([
{
tool: "get_settings",
path: "/api/settings",
value: { theme: "dark", density: "compact" },
record_ordinal: 0,
},
]);
const invented = serving.store.replace({
rea_state: {
version: 1,
entities: [],
documents: [
{
tool: "get_settings",
path: "/api/settings",
value: { theme: "blue" },
record_ordinal: 2,
},
],
},
});
expect(invented.ok || invented.error.issues[0]?.path).toEqual([
"rea_state",
"documents",
0,
"record_ordinal",
]);
load(serving, (entities) => entities, [
{
tool: "get_settings",
path: "/api/settings",
value: "x".repeat(REPLAY_BODY_LIMIT_BYTES),
},
]);
expect(refusal(serving, "get_settings", {})).toMatchObject({
code: "resource_constraint",
details: {
reported_limits: { max_body_bytes: REPLAY_BODY_LIMIT_BYTES },
},
});
load(serving, (entities) => entities);
expect(refusal(serving, "get_settings", {})).toMatchObject({
message: expect.stringContaining("holds no document"),
});
});
});