Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
feat(artifacts): add provider-neutral inspection
morlutod9977286f950
diff --git a/src/application/DirectAnalysis.ts b/src/application/DirectAnalysis.tsindex b3d65d031..2ceac7128 100644--- a/src/application/DirectAnalysis.ts+++ b/src/application/DirectAnalysis.ts@@ -40,6 +40,7 @@ import {workflowAnalysisProfile,} from "./InvestigationProviders.js";import type { AnalysisProviderSelector } from "../contracts/providerSelection.js";+import { artifactInspectionResultSchema } from "../domain/artifactInspection.js";export {runCapabilityStatus,@@ -144,7 +145,7 @@ const authorizeAnalysis = async ();}if (- tool === "inventory_artifact" &&+ ["inventory_artifact", "inspect_artifact"].includes(tool) &&arguments_.native_mount_approved === true) {const result = await authority.authorize(@@ -155,7 +156,7 @@ const authorizeAnalysis = async (environment_names: [],network: "none",mount: true,- operation_identity: "inventory_artifact:native_mount",+ operation_identity: `${tool}:native_mount`,},"read",);@@ -381,6 +382,11 @@ const executeAnalysisTool = async (input: {rawResult: result.value.rawResult,limitations: result.value.limitations,locations: result.value.locations,+ evidenceLinks:+ tool === "inspect_artifact"+ ? artifactInspectionResultSchema.parse(result.value.result)+ .evidence_links+ : [],},);return { output: evidence, evidence };diff --git a/src/artifacts/ArtifactProvider.ts b/src/artifacts/ArtifactProvider.tsindex e0ef5729f..eefcf5851 100644--- a/src/artifacts/ArtifactProvider.ts+++ b/src/artifacts/ArtifactProvider.ts@@ -11,6 +11,7 @@ import { inventoryArtifact } from "../application/ArtifactInventory.js";import { extractArtifact } from "../application/ArtifactExtraction.js";import {ARTIFACT_TOOL_CONTRACTS,+ artifactInspectionInputSchema,artifactInventoryInputSchema,artifactExtractionInputSchema,type ArtifactToolName,@@ -28,6 +29,8 @@ import {type ArtifactLimits,} from "./ArtifactReader.js";import { ARTIFACT_GRAPH_PROVIDER } from "../application/InvestigationProviders.js";+import { createEvidence } from "../domain/evidence.js";+import { createArtifactInspection } from "../domain/artifactInspection.js";const IDENTITY: ProviderIdentity = Object.freeze(ARTIFACT_GRAPH_PROVIDER);@@ -47,7 +50,10 @@ export class ArtifactProvider implements AnalysisProvider {outputContractVersion: 1,available: true as const,reason: null,- pagination: "offset" as const,+ pagination:+ contract.name === "inspect_artifact"+ ? ("none" as const)+ : ("offset" as const),exhaustive: false,effects: Object.freeze({mutatesArtifact: false,@@ -111,6 +117,10 @@ class ArtifactClient implements AnalysisClient {),);try {+ if (operation === "inspect_artifact") {+ const inspected = await this.inspectArtifact(parameters, options);+ return inspected;+ }if (operation === "extract_artifact") {const parsed = artifactExtractionInputSchema.parse(parameters);const result = await extractArtifact(@@ -143,31 +153,7 @@ class ArtifactClient implements AnalysisClient {);}const parsed = artifactInventoryInputSchema.parse(parameters);- const result = await inventoryArtifact(- this.target.sourcePath ?? this.target.path,- limitsFrom(parsed),- {- nodeOffset: parsed.node_offset,- nodeLimit: parsed.node_limit,- occurrenceOffset: parsed.occurrence_offset,- occurrenceLimit: parsed.occurrence_limit,- edgeOffset: parsed.edge_offset,- edgeLimit: parsed.edge_limit,- },- {- ...(options?.signal === undefined ? {} : { signal: options.signal }),- nativeMount: {- nativeMountApproved: parsed.native_mount_approved === true,- nativeMountEnabled: this.nativeMountEnabled,- },- integrity: {- mode: parsed.integrity_policy,- approved: parsed.integrity_continue_approved === true,- enabled: this.integrityContinueEnabled,- maxMismatches: parsed.max_integrity_mismatches,- },- },- );+ const result = await this.inventory(parsed, options);return ok(createAnalysisExecution(result, IDENTITY, {rawResult: null,@@ -190,6 +176,119 @@ class ArtifactClient implements AnalysisClient {close(): Promise<void> {return Promise.resolve();}++ private async inspectArtifact(+ parameters: Readonly<Record<string, JsonValue>>,+ options?: ExecutionOptions,+ ) {+ const parsed = artifactInspectionInputSchema.parse(parameters);+ const inventoryParameters = artifactInventoryInputSchema.parse({+ node_offset: 0,+ node_limit: parsed.max_observations,+ occurrence_offset: 0,+ occurrence_limit: parsed.max_observations,+ edge_offset: 0,+ edge_limit: parsed.max_relationships,+ native_mount_approved: parsed.native_mount_approved,+ integrity_policy: parsed.integrity_policy,+ integrity_continue_approved: parsed.integrity_continue_approved,+ max_integrity_mismatches: parsed.max_integrity_mismatches,+ max_entries: parsed.max_entries,+ max_total_bytes: parsed.max_total_bytes,+ max_entry_bytes: parsed.max_entry_bytes,+ max_compression_ratio: parsed.max_compression_ratio,+ max_depth: parsed.max_depth,+ max_path_bytes: parsed.max_path_bytes,+ });+ await options?.progress?.report({+ phase: "inspect_artifact.inventory",+ completed: 0,+ total: 1,+ message: "inventory substep started",+ });+ const inventory = await this.inventory(inventoryParameters, options);+ const subject = subjectFor(+ this.target.sourcePath ?? this.target.path,+ inventory.manifest,+ );+ const locations = inventory.occurrences.items.map(+ ({ logical_path: path }) => ({+ kind: "artifact-path" as const,+ path,+ }),+ );+ const inventoryEvidence = createEvidence(subject, IDENTITY, {+ operation: "inventory_artifact",+ parameters: inventoryParameters,+ result: inventory,+ rawResult: null,+ limitations: inventory.limitations,+ locations,+ });+ const result = createArtifactInspection(inventoryEvidence, parsed);+ await options?.progress?.report({+ phase: "inspect_artifact.inventory",+ completed: 1,+ total: 1,+ message: "inventory substep completed",+ });+ return ok(+ createAnalysisExecution(result, IDENTITY, {+ rawResult: null,+ limitations: result.limitations,+ subject,+ locations,+ }),+ );+ }++ private inventory(+ parsed: {+ readonly node_offset: number;+ readonly node_limit: number;+ readonly occurrence_offset: number;+ readonly occurrence_limit: number;+ readonly edge_offset: number;+ readonly edge_limit: number;+ readonly native_mount_approved: boolean;+ readonly integrity_policy: "fail" | "record-and-continue";+ readonly integrity_continue_approved: boolean;+ readonly max_integrity_mismatches: number;+ readonly max_entries: number;+ readonly max_total_bytes: number;+ readonly max_entry_bytes: number;+ readonly max_compression_ratio: number;+ readonly max_depth: number;+ readonly max_path_bytes: number;+ },+ options?: ExecutionOptions,+ ) {+ return inventoryArtifact(+ this.target.sourcePath ?? this.target.path,+ limitsFrom(parsed),+ {+ nodeOffset: parsed.node_offset,+ nodeLimit: parsed.node_limit,+ occurrenceOffset: parsed.occurrence_offset,+ occurrenceLimit: parsed.occurrence_limit,+ edgeOffset: parsed.edge_offset,+ edgeLimit: parsed.edge_limit,+ },+ {+ ...(options?.signal === undefined ? {} : { signal: options.signal }),+ nativeMount: {+ nativeMountApproved: parsed.native_mount_approved === true,+ nativeMountEnabled: this.nativeMountEnabled,+ },+ integrity: {+ mode: parsed.integrity_policy,+ approved: parsed.integrity_continue_approved === true,+ enabled: this.integrityContinueEnabled,+ maxMismatches: parsed.max_integrity_mismatches,+ },+ },+ );+ }}const limitsFrom = (input: {diff --git a/src/cli/artifactCommands.ts b/src/cli/artifactCommands.tsindex b172e0b94..1704c5dcf 100644--- a/src/cli/artifactCommands.ts+++ b/src/cli/artifactCommands.ts@@ -10,6 +10,12 @@ export const registerArtifactCommands = (cli: CliInstance,logger: Logger,): void => {+ registerInventoryCommand(cli, logger);+ registerInspectionCommand(cli, logger);+ registerExtractionCommand(cli, logger);+};++const registerInventoryCommand = (cli: CliInstance, logger: Logger): void => {cli.command(CLI_COMMANDS.inventoryArtifact, {description: "Build a bounded deterministic artifact graph",args: z.object({@@ -76,6 +82,9 @@ export const registerArtifactCommands = (),),});+};++const registerExtractionCommand = (cli: CliInstance, logger: Logger): void => {cli.command(CLI_COMMANDS.extractArtifact, {description: "Extract explicitly selected artifact occurrences safely",args: z.object({@@ -103,3 +112,45 @@ export const registerArtifactCommands = (),});};++const registerInspectionCommand = (cli: CliInstance, logger: Logger): void => {+ cli.command(CLI_COMMANDS.inspectArtifact, {+ description:+ "Inspect one artifact with bounded observations and explicit next probes",+ args: z.object({+ path: z.string().describe("Application or package path"),+ }),+ options: z.object({+ maxObservations: z+ .number()+ .int()+ .min(1)+ .max(500)+ .default(100)+ .describe("Maximum retained observations"),+ maxRelationships: z+ .number()+ .int()+ .min(1)+ .max(500)+ .default(100)+ .describe("Maximum retained derived relationships"),+ }),+ alias: {+ maxObservations: "max-observations",+ maxRelationships: "max-relationships",+ },+ run: ({ args, options }) =>+ logCliCommand(logger, "inspect-artifact", () =>+ runProviderAnalysis(+ args.path,+ "inspect_artifact",+ {+ max_observations: options.maxObservations,+ max_relationships: options.maxRelationships,+ },+ logger,+ ),+ ),+ });+};diff --git a/src/contracts/artifactToolContracts.ts b/src/contracts/artifactToolContracts.tsindex 7ada8bcdb..66ac62698 100644--- a/src/contracts/artifactToolContracts.ts+++ b/src/contracts/artifactToolContracts.ts@@ -4,6 +4,7 @@ import type { ToolContract } from "./toolContracts.js";import { artifactOutputSchemas } from "./toolOutputSchemas.js";import { jsonValueSchema } from "../domain/jsonValue.js";import { toolContractMetadata } from "./toolEffects.js";+import { artifactInspectionLimitsSchema } from "../domain/artifactInspection.js";const pageInput = {node_offset: z.number().int().min(0).default(0),@@ -68,9 +69,32 @@ export const artifactExtractionInputSchema = z.object({...traversalLimitsInput,});+/** Bounded provider-neutral inspection using one atomic inventory substep. */+export const artifactInspectionInputSchema = z+ .object({+ native_mount_approved: z.boolean().default(false),+ integrity_policy: z.enum(["fail", "record-and-continue"]).default("fail"),+ integrity_continue_approved: z.boolean().default(false),+ max_integrity_mismatches: z.number().int().min(1).max(100).default(10),+ ...artifactInspectionLimitsSchema.shape,+ ...traversalLimitsInput,+ })+ .superRefine((input, context) => {+ if (+ input.integrity_policy === "record-and-continue" &&+ input.integrity_continue_approved !== true+ )+ context.addIssue({+ code: "custom",+ path: ["integrity_continue_approved"],+ message: "record-and-continue requires explicit approval",+ });+ });+const exampleInputSchema = z.record(z.string(), jsonValueSchema);const examples: Readonly<Record<string, Readonly<Record<string, unknown>>>> = {inventory_artifact: {},+ inspect_artifact: {},extract_artifact: {approved: true,output_root: "/tmp/rea-extracted",@@ -109,6 +133,11 @@ export const ARTIFACT_TOOL_CONTRACTS = ["Inventory the active application or package as a deterministic, content-addressed artifact graph. Returns bounded node and edge pages without extracting or mounting by default.",artifactInventoryInputSchema,),+ artifact(+ "inspect_artifact",+ "Inspect the active artifact through one bounded, cancellable inventory substep. Returns the full substep Evidence and its ID, observations, derived relationships, hypotheses, contradictions, unexplored branches, limitations, and format-specific next probes. Any substep failure fails the whole call.",+ artifactInspectionInputSchema,+ ),artifact("extract_artifact","Extract selected graph artifacts beneath an explicit output root. Requires approval, rejects traversal and symlink escapes, never overwrites, enforces bomb limits, and verifies cleanup.",diff --git a/src/domain/artifactInspection.ts b/src/domain/artifactInspection.tsnew file mode 100644index 000000000..89a84c90e--- /dev/null+++ b/src/domain/artifactInspection.ts@@ -0,0 +1,476 @@+import { createHash } from "node:crypto";++import canonicalize from "canonicalize";+import { z } from "zod";++import {+ artifactInventoryResultSchema,+ type ArtifactInventoryResult,+} from "./artifactGraph.js";+import { evidenceSchema, parseEvidence, type Evidence } from "./evidence.js";+import { jsonValueSchema } from "./jsonValue.js";++const boundedTextSchema = z.string().min(1).max(4_096);+const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);+const artifactIdSchema = z.string().regex(/^art_[a-f0-9]{64}$/u);++const inspectionLimitsSchema = z.strictObject({+ max_observations: z.number().int().min(1).max(500).default(100),+ max_relationships: z.number().int().min(1).max(500).default(100),+ max_hypotheses: z.number().int().min(1).max(100).default(20),+ max_unexplored_branches: z.number().int().min(1).max(100).default(20),+ max_next_probes: z.number().int().min(1).max(50).default(20),+ max_substeps: z.literal(1).default(1),+});++export const artifactInspectionLimitsSchema = inspectionLimitsSchema;++const inspectionObservationSchema = z.strictObject({+ observation_id: z.string().regex(/^aio_[a-f0-9]{64}$/u),+ kind: z.enum(["root-manifest", "artifact", "occurrence", "integrity"]),+ subject: boundedTextSchema,+ value: jsonValueSchema,+ evidence_id: evidenceIdSchema,+});++const inspectionRelationshipSchema = z.strictObject({+ relationship_id: z.string().regex(/^air_[a-f0-9]{64}$/u),+ relation: z.enum([+ "contains",+ "extracts",+ "slice-of",+ "embeds",+ "loads",+ "maps-source",+ "derived-from",+ ]),+ source_artifact_id: artifactIdSchema,+ target_artifact_id: artifactIdSchema,+ occurrence_id: z.string().regex(/^occ_[a-f0-9]{64}$/u),+ logical_path: boundedTextSchema.nullable(),+ evidence_id: evidenceIdSchema,+});++const inspectionHypothesisSchema = z.strictObject({+ hypothesis_id: z.string().regex(/^aih_[a-f0-9]{64}$/u),+ statement: boundedTextSchema,+ confidence: z.enum(["medium", "low"]),+ basis_evidence_ids: z.array(evidenceIdSchema).min(1).max(8),+ limitation: boundedTextSchema,+});++const inspectionContradictionSchema = z.strictObject({+ contradiction_id: z.string().regex(/^aic_[a-f0-9]{64}$/u),+ statement: boundedTextSchema,+ occurrence_id: z.string().regex(/^occ_[a-f0-9]{64}$/u),+ declared_sha256: z.string().regex(/^[a-f0-9]{64}$/u),+ observed_sha256: z.string().regex(/^[a-f0-9]{64}$/u),+ evidence_id: evidenceIdSchema,+});++const nextProbeSchema = z.strictObject({+ operation: z.string().min(1).max(128),+ rationale: boundedTextSchema,+ authority: z.enum([+ "artifact-bytes",+ "managed-static-analysis",+ "native-analysis-provider",+ "ast-static-analysis",+ ]),+});++const unexploredBranchSchema = z.strictObject({+ branch_id: z.string().regex(/^aib_[a-f0-9]{64}$/u),+ reason: z.enum([+ "page-limit",+ "format-specific-analysis-required",+ "unknown-format",+ ]),+ detail: boundedTextSchema,+ next_probe: nextProbeSchema.nullable(),+ evidence_id: evidenceIdSchema,+});++/** Provider-neutral inspection result with its atomic source Evidence. */+export const artifactInspectionResultSchema = z.strictObject({+ schema_version: z.literal(1),+ inspection_id: z.string().regex(/^ai_[a-f0-9]{64}$/u),+ subject: z.strictObject({+ manifest_id: z.string().regex(/^agm_[a-f0-9]{64}$/u),+ root_artifact_id: artifactIdSchema,+ root_sha256: z.string().regex(/^[a-f0-9]{64}$/u),+ root_format: z.string().min(1).max(128),+ }),+ substeps: z+ .array(+ z.strictObject({+ substep_id: z.string().regex(/^ais_[a-f0-9]{64}$/u),+ operation: z.literal("inventory_artifact"),+ status: z.literal("completed"),+ evidence_id: evidenceIdSchema,+ evidence: evidenceSchema,+ }),+ )+ .min(1)+ .max(1),+ observations: z.array(inspectionObservationSchema).max(500),+ derived_relationships: z.array(inspectionRelationshipSchema).max(500),+ hypotheses: z.array(inspectionHypothesisSchema).max(100),+ contradictions: z.array(inspectionContradictionSchema).max(100),+ unexplored_branches: z.array(unexploredBranchSchema).max(100),+ next_probes: z.array(nextProbeSchema).max(50),+ coverage: z.strictObject({+ status: z.enum(["complete-within-substeps", "partial", "truncated"]),+ substeps_completed: z.literal(1),+ observations_retained: z.number().int().min(0),+ observations_omitted: z.number().int().min(0),+ relationships_retained: z.number().int().min(0),+ relationships_omitted: z.number().int().min(0),+ hypotheses_retained: z.number().int().min(0),+ hypotheses_omitted: z.number().int().min(0),+ unexplored_branches_retained: z.number().int().min(0),+ unexplored_branches_omitted: z.number().int().min(0),+ next_probes_retained: z.number().int().min(0),+ next_probes_omitted: z.number().int().min(0),+ }),+ evidence_links: z.array(evidenceIdSchema).min(1).max(1),+ limitations: z.array(boundedTextSchema).max(1_000),+});++export type ArtifactInspectionLimits = z.infer<+ typeof artifactInspectionLimitsSchema+>;+export type ArtifactInspectionResult = z.infer<+ typeof artifactInspectionResultSchema+>;++/** Project one successful inventory Evidence record into an inspection report. */+export const createArtifactInspection = (+ inventoryInput: unknown,+ limits: ArtifactInspectionLimits,+): ArtifactInspectionResult => {+ const inventoryEvidence = parseInventoryEvidence(inventoryInput);+ const inventory = artifactInventoryResultSchema.parse(+ inventoryEvidence.normalized_result,+ );+ const observations = allObservations(+ inventory,+ inventoryEvidence.evidence_id,+ );+ const relationships = allRelationships(+ inventory,+ inventoryEvidence.evidence_id,+ );+ const hypotheses = allHypotheses(inventory, inventoryEvidence.evidence_id);+ const nextProbes = probesFor(inventory);+ const branches = allUnexploredBranches(+ inventory,+ inventoryEvidence.evidence_id,+ nextProbes,+ );+ const retained = {+ observations: observations.slice(0, limits.max_observations),+ relationships: relationships.slice(0, limits.max_relationships),+ hypotheses: hypotheses.slice(0, limits.max_hypotheses),+ branches: branches.slice(0, limits.max_unexplored_branches),+ probes: nextProbes.slice(0, limits.max_next_probes),+ };+ const omissions = {+ observations: observations.length - retained.observations.length,+ relationships: relationships.length - retained.relationships.length,+ hypotheses: hypotheses.length - retained.hypotheses.length,+ branches: branches.length - retained.branches.length,+ probes: nextProbes.length - retained.probes.length,+ };+ const semantic = {+ schema_version: 1 as const,+ subject: {+ manifest_id: inventory.manifest.manifest_id,+ root_artifact_id: inventory.manifest.root_artifact_id,+ root_sha256: inventory.manifest.root_sha256,+ root_format: inventory.manifest.root_format,+ },+ substeps: [+ {+ substep_id: `ais_${digestCanonical({+ operation: "inventory_artifact",+ evidence_id: inventoryEvidence.evidence_id,+ })}`,+ operation: "inventory_artifact" as const,+ status: "completed" as const,+ evidence_id: inventoryEvidence.evidence_id,+ evidence: inventoryEvidence,+ },+ ],+ observations: retained.observations,+ derived_relationships: retained.relationships,+ hypotheses: retained.hypotheses,+ contradictions: contradictions(inventory, inventoryEvidence.evidence_id),+ unexplored_branches: retained.branches,+ next_probes: retained.probes,+ coverage: {+ status: inspectionCoverage(inventory, omissions),+ substeps_completed: 1 as const,+ observations_retained: retained.observations.length,+ observations_omitted: omissions.observations,+ relationships_retained: retained.relationships.length,+ relationships_omitted: omissions.relationships,+ hypotheses_retained: retained.hypotheses.length,+ hypotheses_omitted: omissions.hypotheses,+ unexplored_branches_retained: retained.branches.length,+ unexplored_branches_omitted: omissions.branches,+ next_probes_retained: retained.probes.length,+ next_probes_omitted: omissions.probes,+ },+ evidence_links: [inventoryEvidence.evidence_id],+ limitations: uniqueSorted([+ ...inventory.limitations,+ "Inspection derives bounded static hypotheses and next probes; it does not execute the artifact or claim format-specific semantics.",+ ]),+ };+ return artifactInspectionResultSchema.parse({+ ...semantic,+ inspection_id: `ai_${digestCanonical(semantic)}`,+ });+};++const parseInventoryEvidence = (input: unknown): Evidence => {+ const evidence = parseEvidence(input);+ if (evidence.operation !== "inventory_artifact")+ throw new TypeError(+ "Artifact inspection substep requires inventory_artifact Evidence",+ );+ return evidence;+};++const allObservations = (+ inventory: ArtifactInventoryResult,+ evidenceId: string,+): ArtifactInspectionResult["observations"] => [+ observation(+ "root-manifest",+ inventory.manifest.root_artifact_id,+ inventory.manifest,+ evidenceId,+ ),+ ...inventory.nodes.items.map((node) =>+ observation("artifact", node.artifact_id, node, evidenceId),+ ),+ ...inventory.occurrences.items.map((occurrence) =>+ observation("occurrence", occurrence.occurrence_id, occurrence, evidenceId),+ ),+ ...inventory.integrity_contradictions.map((value) =>+ observation("integrity", value.contradiction_id, value, evidenceId),+ ),+];++const observation = (+ kind: ArtifactInspectionResult["observations"][number]["kind"],+ subject: string,+ value: unknown,+ evidenceId: string,+): ArtifactInspectionResult["observations"][number] => {+ const semantic = {+ kind,+ subject,+ value: jsonValueSchema.parse(value),+ evidence_id: evidenceId,+ };+ return { observation_id: `aio_${digestCanonical(semantic)}`, ...semantic };+};++const allRelationships = (+ inventory: ArtifactInventoryResult,+ evidenceId: string,+): ArtifactInspectionResult["derived_relationships"] =>+ inventory.edges.items.map((edge) => {+ const semantic = {+ relation: edge.relation,+ source_artifact_id: edge.parent_artifact_id,+ target_artifact_id: edge.child_artifact_id,+ occurrence_id: edge.occurrence_id,+ logical_path: edge.logical_path,+ evidence_id: evidenceId,+ };+ return {+ relationship_id: `air_${digestCanonical(semantic)}`,+ ...semantic,+ };+ });++const allHypotheses = (+ inventory: ArtifactInventoryResult,+ evidenceId: string,+): ArtifactInspectionResult["hypotheses"] => {+ const statements =+ inventory.manifest.root_format === "pe"+ ? [+ "The PE artifact may contain managed CLI metadata or native code; inventory bytes alone do not distinguish them.",+ ]+ : ["asar", "javascript-bundle"].includes(inventory.manifest.root_format)+ ? [+ "The artifact may contain a recoverable JavaScript application graph.",+ ]+ : [];+ return statements.map((statement) => {+ const semantic = {+ statement,+ confidence: "low" as const,+ basis_evidence_ids: [evidenceId],+ limitation:+ "Format classification proposes a bounded follow-up; it is not semantic proof.",+ };+ return { hypothesis_id: `aih_${digestCanonical(semantic)}`, ...semantic };+ });+};++const contradictions = (+ inventory: ArtifactInventoryResult,+ evidenceId: string,+): ArtifactInspectionResult["contradictions"] =>+ inventory.integrity_contradictions.map((value) => {+ const semantic = {+ statement: `Declared integrity for ${value.logical_path} contradicts observed bytes.`,+ occurrence_id: value.occurrence_id,+ declared_sha256: value.declared_sha256,+ observed_sha256: value.observed_sha256,+ evidence_id: evidenceId,+ };+ return {+ contradiction_id: `aic_${digestCanonical(semantic)}`,+ ...semantic,+ };+ });++const probesFor = (+ inventory: ArtifactInventoryResult,+): ArtifactInspectionResult["next_probes"] => {+ const format = inventory.manifest.root_format;+ if (["asar", "javascript-bundle", "directory"].includes(format))+ return [+ {+ operation: "analyze_javascript_application",+ rationale:+ "Recover bounded JavaScript modules, source maps, Electron boundaries, and application relationships.",+ authority: "ast-static-analysis",+ },+ ];+ if (format === "pe")+ return [+ {+ operation: "inspect_managed_artifact",+ rationale:+ "Check execution-free CLI metadata before choosing a deep native provider.",+ authority: "managed-static-analysis",+ },+ {+ operation: "open_binary",+ rationale:+ "Open as native code only when managed inspection reports a native or mixed boundary.",+ authority: "native-analysis-provider",+ },+ ];+ if (["mach-o", "mach-o-universal", "elf"].includes(format))+ return [+ {+ operation: "open_binary",+ rationale:+ "Bind one deep native provider before function-level analysis.",+ authority: "native-analysis-provider",+ },+ ];+ if (format === "plist")+ return [+ {+ operation: "inspect_plist",+ rationale: "Parse property-list values without executing the artifact.",+ authority: "artifact-bytes",+ },+ ];+ return [];+};++const allUnexploredBranches = (+ inventory: ArtifactInventoryResult,+ evidenceId: string,+ nextProbes: ArtifactInspectionResult["next_probes"],+): ArtifactInspectionResult["unexplored_branches"] => {+ const pages = [+ ["nodes", inventory.nodes.next_offset],+ ["occurrences", inventory.occurrences.next_offset],+ ["relationships", inventory.edges.next_offset],+ ] as const;+ const branches = pages.flatMap(([collection, nextOffset]) =>+ nextOffset === null+ ? []+ : [+ branch(+ "page-limit",+ `${collection} continue at offset ${String(nextOffset)}.`,+ null,+ evidenceId,+ ),+ ],+ );+ branches.push(+ ...nextProbes.map((probe) =>+ branch(+ "format-specific-analysis-required",+ `${probe.operation} was not run by provider-neutral artifact inspection.`,+ probe,+ evidenceId,+ ),+ ),+ );+ if (inventory.manifest.root_format === "unknown")+ branches.push(+ branch(+ "unknown-format",+ "Artifact bytes did not match an admitted format classifier.",+ null,+ evidenceId,+ ),+ );+ return branches;+};++const branch = (+ reason: ArtifactInspectionResult["unexplored_branches"][number]["reason"],+ detail: string,+ nextProbe: ArtifactInspectionResult["next_probes"][number] | null,+ evidenceId: string,+): ArtifactInspectionResult["unexplored_branches"][number] => {+ const semantic = {+ reason,+ detail,+ next_probe: nextProbe,+ evidence_id: evidenceId,+ };+ return { branch_id: `aib_${digestCanonical(semantic)}`, ...semantic };+};++const inspectionCoverage = (+ inventory: ArtifactInventoryResult,+ omissions: Readonly<Record<string, number>>,+): ArtifactInspectionResult["coverage"]["status"] => {+ if (Object.values(omissions).some((count) => count > 0)) return "truncated";+ return [+ inventory.nodes.next_offset,+ inventory.occurrences.next_offset,+ inventory.edges.next_offset,+ ].some((offset) => offset !== null)+ ? "partial"+ : "complete-within-substeps";+};++const digestCanonical = (value: unknown): string => {+ const encoded = canonicalize(value);+ if (encoded === undefined)+ throw new TypeError("Artifact inspection could not canonicalize");+ return createHash("sha256").update(encoded).digest("hex");+};++const uniqueSorted = (values: readonly string[]): string[] =>+ [...new Set(values)].sort((left, right) =>+ left < right ? -1 : left > right ? 1 : 0,+ );diff --git a/src/server/registerArtifactTools.ts b/src/server/registerArtifactTools.tsindex 2cf7a5844..092ab0c32 100644--- a/src/server/registerArtifactTools.ts+++ b/src/server/registerArtifactTools.ts@@ -7,6 +7,7 @@ import type { BinaryTarget } from "../domain/binaryTarget.js";import type { Logger } from "../logger.js";import { registerEvidenceTools } from "./registerEvidenceTools.js";import type { PermissionAuthority } from "../application/PermissionAuthority.js";+import { artifactInspectionResultSchema } from "../domain/artifactInspection.js";/** Register deterministic artifact inventory and safe extraction operations. */export const registerArtifactTools = (@@ -19,5 +20,13 @@ export const registerArtifactTools = (readonly permissionAuthority?: PermissionAuthority;},): void => {- registerEvidenceTools(server, analysis, ARTIFACT_TOOL_CONTRACTS, options);+ registerEvidenceTools(server, analysis, ARTIFACT_TOOL_CONTRACTS, {+ ...options,+ sourceEvidence: (operation, result) =>+ operation === "inspect_artifact"+ ? artifactInspectionResultSchema+ .parse(result)+ .substeps.map(({ evidence }) => evidence)+ : [],+ });};diff --git a/tests/artifactMcp.test.ts b/tests/artifactMcp.test.tsindex 230f01446..8a030ee84 100644--- a/tests/artifactMcp.test.ts+++ b/tests/artifactMcp.test.ts@@ -196,6 +196,26 @@ describe("artifact graph MCP integration", () => {}),]),);+ const inspected = await client.callTool({+ name: "inspect_artifact",+ arguments: {+ integrity_policy: "record-and-continue",+ integrity_continue_approved: true,+ },+ });+ expect(inspected.isError).not.toBe(true);+ expect(compactResult(inspected.structuredContent).result).toMatchObject({+ contradictions: [+ expect.objectContaining({ occurrence_id: expect.any(String) }),+ expect.objectContaining({ occurrence_id: expect.any(String) }),+ ],+ substeps: [+ expect.objectContaining({+ operation: "inventory_artifact",+ status: "completed",+ }),+ ],+ });const compared = await client.callTool({name: "compare_artifacts",arguments: {@@ -326,6 +346,44 @@ describe("artifact graph MCP integration", () => {arguments: { path: archive },});expect(opened.isError).not.toBe(true);+ const inspected = await client.callTool({+ name: "inspect_artifact",+ arguments: { max_observations: 1, max_relationships: 1 },+ });+ expect(inspected.isError).not.toBe(true);+ const inspectionResult = compactResult(inspected.structuredContent);+ const inspectionEvidence = session.evidenceById(+ inspectionResult.evidence_id,+ );+ if (inspectionEvidence === undefined)+ throw new Error("missing inspection Evidence");+ const inspection = z+ .object({+ substeps: z.array(+ z.object({+ evidence_id: z.string(),+ status: z.literal("completed"),+ }),+ ),+ coverage: z.object({+ status: z.literal("truncated"),+ substeps_completed: z.literal(1),+ }),+ unexplored_branches: z.array(z.object({ reason: z.string() })),+ })+ .parse(inspectionResult.result);+ expect(inspection.substeps).toHaveLength(1);+ expect(+ session.evidenceById(inspection.substeps[0]?.evidence_id ?? ""),+ ).toMatchObject({ operation: "inventory_artifact" });+ expect(inspectionEvidence.evidence_links).toEqual([+ inspection.substeps[0]?.evidence_id,+ ]);+ expect(inspection.unexplored_branches).toEqual(+ expect.arrayContaining([+ expect.objectContaining({ reason: "page-limit" }),+ ]),+ );const inventory = await client.callTool({name: "inventory_artifact",arguments: {},@@ -381,7 +439,7 @@ describe("artifact graph MCP integration", () => {const envelope = z.object({ result: evidenceBundleSchema }).parse(exported.structuredContent);- expect(envelope.result.records).toHaveLength(4);+ expect(envelope.result.records).toHaveLength(6);expect(envelope.result.artifacts).toContainEqual({digest: { sha256: evidence.subject?.digest.sha256 },format: "ipa",diff --git a/tests/artifactProvider.test.ts b/tests/artifactProvider.test.tsindex 0a72c5307..d3852aebb 100644--- a/tests/artifactProvider.test.ts+++ b/tests/artifactProvider.test.ts@@ -23,6 +23,7 @@ import {} from "../src/artifacts/ArtifactPaths.js";import {artifactExtractionInputSchema,+ artifactInspectionInputSchema,artifactInventoryInputSchema,} from "../src/contracts/artifactToolContracts.js";import type { BinaryTarget } from "../src/domain/binaryTarget.js";@@ -34,6 +35,7 @@ import {artifactExtractionResultSchema,artifactInventoryResultSchema,} from "../src/domain/artifactGraph.js";+import { artifactInspectionResultSchema } from "../src/domain/artifactInspection.js";describe("artifact graph provider", () => {it("inventories app trees deterministically without following symlinks", async () => {@@ -124,6 +126,28 @@ describe("artifact graph provider", () => {provider: { id: "rea-artifact-graph" },subject: { format: "apk" },});+ const inspectionEvidence = parseEvidence(+ await runProviderAnalysis(zipPath, "inspect_artifact", {+ max_observations: 2,+ max_relationships: 1,+ }),+ );+ const inspection = artifactInspectionResultSchema.parse(+ inspectionEvidence.normalized_result,+ );+ expect(inspection).toMatchObject({+ substeps: [+ {+ operation: "inventory_artifact",+ status: "completed",+ evidence_id: expect.stringMatching(/^ev_[a-f0-9]{64}$/u),+ },+ ],+ coverage: { status: "truncated", substeps_completed: 1 },+ });+ expect(inspectionEvidence.evidence_links).toEqual(+ inspection.evidence_links,+ );const cancellation = new AbortController();cancellation.abort();await expect(@@ -135,6 +159,15 @@ describe("artifact graph provider", () => {cancellation.signal,),).resolves.toMatchObject({ code: "cancelled" });+ await expect(+ runProviderAnalysis(+ zipPath,+ "inspect_artifact",+ {},+ undefined,+ cancellation.signal,+ ),+ ).resolves.toMatchObject({ code: "cancelled" });const source = join(root, "asar-source");await mkdir(source);@@ -177,6 +210,13 @@ describe("artifact graph provider", () => {},},});+ const failedInspection = await new ArtifactProvider()+ .createClient(target(unpackedPath, "asar"))+ .execute("inspect_artifact", artifactInspectionInputSchema.parse({}));+ expect(failedInspection).toMatchObject({+ ok: false,+ error: { _tag: "ArtifactOperationError", reason: "integrity" },+ });});it.each([